Troubleshoot Laravel Cloud API allowlisting
Start by identifying where the request failed. Configuration, the proxy connection, destination TLS, the destination allowlist, and the API’s own authorization are separate layers. Checking them in order is faster than changing all of them at once.
Keep the failing environment, release identifier, execution path, UTC time, destination hostname, and sanitized status or request identifier. Do not paste a proxy URL, Authorization header, raw exception, wallet response, or other sensitive response body into a ticket.
The “QuotaGuard proxy is not configured” error appears
The selected factory did not receive a nonempty quotaguard.proxy_url value. It stopped before sending a request.
Check that config/quotaguard.php exists in the deployed code. Confirm QUOTAGUARDSTATIC_URL is linked to the correct Cloud environment, then inspect whether a custom variable with the same name overrides the organization secret. Redeploy after correcting the setting. Do not print config('quotaguard.proxy_url') to prove it exists.
If the application caches configuration, review the build process. Reading env() directly from runtime code can behave differently after caching. Keep environment access in configuration files and use config() in the factory. Laravel configuration caching explains the behavior.
A credential rotation still uses the previous connection
A changed organization secret does not override an identically named custom environment variable. Remove or correct the stale override through the authorized environment workflow and redeploy. Also confirm you changed the secret linked to this environment rather than a similarly named staging secret.
Check the release actually reached the relevant app and worker environment. Do not infer that a saved settings screen changed a process already serving requests. Follow Cloud’s secret and precedence rules.
The command shows an unexpected IPv4 address
Do not count a 200 response as a passing route check. Compare the address with the assigned pair from the intended subscription.
Confirm that the deployed command uses QuotaGuardHttp::client(). Check for a custom Guzzle handler, request options that overwrite proxy, or a different SDK path. The example’s empty CURLOPT_NOPROXY applies to the cURL handle; it is not a guarantee for another transport. Review libcurl bypass behavior.
Also check whether the expected pair came from the wrong subscription or a previous shared-to-dedicated migration. Correct the configuration reference rather than accepting an arbitrary echoed value.
The echo passes but the API rejects the request
The echo and the API are different requests. Confirm the API path uses the same configured client. Then confirm both assigned addresses are present in the correct provider environment’s allowlist.
If the source is accepted, review API credentials, account permissions, destination hostname, versioned path, headers, request data, and provider-specific responses. A matching source IP does not establish API authorization or business success. Ask the provider for a request correlation or observed source where available rather than assigning every 403 to an IP failure.
Some calls succeed and others fail
First split failures by execution path and destination. Does the same service create requests in controllers and jobs, or does one path use a new Http instance or SDK? Does one hostname redirect to another? Do failures occur only when an address missing from the allowlist is selected?
Register both assigned addresses. Repeated echo calls may keep showing the same one and do not prove that failover or balancing can never use the other. Do not generate a large stream of diagnostic traffic hoping to force a second address. QuotaGuard’s two-address guidance makes the registration requirement explicit.
Web requests pass but queue jobs fail
Cloud workers share their environment’s code and variables, but jobs can construct their own transport. Check the actual job service, queue connection, worker process, and release. A diagnostic dispatched to a sync connection only ran inline.
Use the real queue diagnostic and wait for completion in private worker logs. A successful dispatch is not proof that the worker ran. Cloud handles queue-worker restarts during deployment; avoid adding redundant restart commands as a first response. Cloud workers documents that lifecycle.
The queue diagnostic never completes
Inspect the configured queue, whether a worker consumes it, failed-job state, and the worker’s existing timeout and retry policy. Check for an application bootstrap or dependency error before blaming networking. The example job’s one attempt is deliberate so a diagnostic does not repeatedly send traffic in the background.
If the diagnostic logged a success, that covers the worker echo path. It still does not prove that the actual business job calls the provider through the same client.
The proxy returns an authentication failure
Review the full current dashboard connection URL, including hostname, port, and credentials. Preserve percent-encoded components rather than manually rebuilding the URL. Check that the configured subscription and product match the chosen client transport. Keep the full URL private.
A proxy authentication response is a different stage from a destination API authentication response. Use the source of the status and private logs to distinguish them. Do not send the provider’s Bearer token as proxy credentials or the proxy password as API authentication.
The request times out
A timeout alone does not identify the cause. Separate inability to reach the proxy from a slow destination or a request that the destination may already have processed. Review proxy host and port, destination DNS and IPv4 reachability, selected region, TLS, and the provider’s availability.
Keep bounded timeouts. Increasing them indefinitely makes a worker harder to recover. For writes, use the provider’s documented idempotency and transaction lookup process before retrying. Never assume a timed-out write is safe to repeat through a direct connection.
The response is a redirect
The example deliberately disables automatic redirects. Inspect the destination and choose the provider’s documented final HTTPS endpoint. A redirect may change the hostname or authorization boundary. Do not globally enable redirects just to silence a diagnostic failure.
TLS or certificate validation fails
Leave certificate and hostname verification enabled. Review the destination hostname, certificate chain, client trust store, PHP/cURL build, and whether the selected proxy protocol is supported. Do not fix a TLS error with verify => false or withoutVerifying().
Static and Shield have different application-to-proxy transport requirements. Switching a URL’s scheme or port by guesswork is not a migration procedure. Use the actual dashboard settings and a supported client configuration. HTTPS proxying guidance describes the distinction.
What to include when requesting help
Prepare a sanitized record with the environment, UTC time window, release identifier, PHP and cURL versions, Guzzle version from the lockfile, product and proxy protocol, destination hostname, execution path, status category, and whether both assigned addresses are approved. State which evidence came from an echo request and which came from the destination.
Never include the full proxy URL, API key, raw request body, raw exception stack, or confidential response data in a public issue. If a support engineer needs additional diagnostics, agree on a private, redacted collection method first.
Download the reference examples · Integration overview