{"id":"bd05f8c06a966f98","repo":"laravel/framework","slug":"the-laravel-cloud-agent-returned-http-response","errorCode":null,"errorMessage":"The Laravel Cloud agent returned HTTP {$response->status()} from GET /next.","messagePattern":"The Laravel Cloud agent returned HTTP (.+?) from GET /next\\.","errorType":"exception","errorClass":"AgentUnreachableException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Foundation/Cloud/Queue.php","lineNumber":270,"sourceCode":"     */\n    protected function requestNextJobFromAgent(): ?array\n    {\n        try {\n            $response = $this->agentRequest()\n                ->timeout(65)\n                ->get('/next');\n        } catch (ConnectionException $e) {\n            throw new AgentUnreachableException(\n                'The Laravel Cloud agent runtime socket is unreachable.', previous: $e\n            );\n        }\n\n        if ($response->status() === 204) {\n            return null;\n        }\n\n        if (! $response->ok()) {\n            throw new AgentUnreachableException(\n                \"The Laravel Cloud agent returned HTTP {$response->status()} from GET /next.\"\n            );\n        }\n\n        if (! is_array($data = $response->json())) {\n            throw new AgentUnreachableException(\n                'The Laravel Cloud agent returned a non-array body from GET /next.'\n            );\n        }\n\n        return $data;\n    }\n\n    /**\n     * Report a job's terminal outcome back to the agent (POST /result).\n     *\n     * @throws \\Illuminate\\Http\\Client\\RequestException\n     * @throws \\Illuminate\\Foundation\\Cloud\\AgentUnreachableException","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Foundation/Cloud/Queue.php#L252-L288","documentation":"Thrown as AgentUnreachableException from Queue::requestNextJobFromAgent() when GET /next returns a non-2xx status other than 204. A 204 means no work (returns null); any other error status (4xx/5xx) means the agent answered but reported a problem, so the worker cannot continue polling. The HTTP status is interpolated into the message.","triggerScenarios":"The Cloud agent process responds with an error (e.g. 401 auth, 404 misconfigured endpoint, 500 internal agent error, 503 overloaded) to the GET /next long-poll. Surfaces inside the worker loop on the cloud connection.","commonSituations":"Agent version mismatch with the SDK. Agent-side bug or crash returning 500. Auth/credential issue returning 4xx. Agent temporarily overloaded during a spike. Endpoint/route regression after an upgrade.","solutions":["Inspect the agent logs for the corresponding request — the status code narrows the cause.","Restart the agent / redeploy; transient 5xx often clears on restart.","Verify Cloud agent and SDK versions are compatible (upgrade/downgrade to a matched pair).","Check auth/credentials configuration if the status is 4xx.","Handle AgentUnreachableException in the worker with backoff to ride out transient agent errors."],"exampleFix":"// before\n$job = $queue->requestNextJobFromAgent();\n\n// after\nuse Illuminate\\Foundation\\Cloud\\AgentUnreachableException;\n\ntry {\n    $job = $queue->requestNextJobFromAgent();\n} catch (AgentUnreachableException $e) {\n    report($e);\n    // back off and retry the poll; surface to monitoring\n    throw $e;\n}","handlingStrategy":"try-catch","validationCode":"// Pre-check is limited; you can ping the agent before the long poll:\nuse Illuminate\\Support\\Facades\\Http;\n\n$resp = Http::withOptions(['curl' => [CURLOPT_UNIX_SOCKET_PATH => config('queue.connections.cloud.agent.socket', '/tmp/cloud-agent.sock')]])->get('http://localhost/health');\nif (! $resp->ok()) {\n    throw new \\RuntimeException('Cloud agent health check failed: '.$resp->status());\n}","typeGuard":"// Not type-based. Treat any AgentUnreachableException as transient-or-fatal based on monitoring.","tryCatchPattern":"use Illuminate\\Foundation\\Cloud\\AgentUnreachableException;\n\ntry {\n    $job = $queue->requestNextJobFromAgent();\n} catch (AgentUnreachableException $e) {\n    if (str_contains($e->getMessage(), 'returned HTTP')) {\n        report($e); // agent answered with an error — back off, escalate if persistent\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Keep Cloud agent and SDK versions matched; check release notes on upgrade.","Monitor agent error rates; persistent non-2xx usually means a version/auth mismatch.","Add a /health probe before starting workers."],"tags":["laravel-cloud","queue","agent-unreachable","http-status","network"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}