{"id":"bb1479ac283d2c63","repo":"laravel/framework","slug":"the-laravel-cloud-agent-runtime-socket-is-unreacha","errorCode":null,"errorMessage":"The Laravel Cloud agent runtime socket is unreachable.","messagePattern":"The Laravel Cloud agent runtime socket is unreachable\\.","errorType":"exception","errorClass":"AgentUnreachableException","httpStatus":null,"severity":"critical","filePath":"src/Illuminate/Foundation/Cloud/Queue.php","lineNumber":260,"sourceCode":"                $messageId, $receiptHandle, $status, $delay\n            ),\n            $this->config['connection']['overflow'] ?? [],\n        );\n    }\n\n    /**\n     * Long-poll the agent's runtime socket (GET /next) for the next job.\n     *\n     * @throws \\Illuminate\\Foundation\\Cloud\\AgentUnreachableException\n     */\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            );","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Foundation/Cloud/Queue.php#L242-L278","documentation":"Thrown as AgentUnreachableException from Queue::requestNextJobFromAgent() when the HTTP request to GET /next on the Cloud agent runtime socket raises an Illuminate\\Http\\Client\\ConnectionException. The worker long-polls the agent (timeout 65s) for the next job; if the Unix socket at config.agent.socket (default /tmp/cloud-agent.sock) cannot be connected, the worker cannot dequeue. AgentUnreachableException wraps the underlying ConnectionException as its `previous`.","triggerScenarios":"A Cloud queue worker (queue:work on the cloud connection) calling requestNextJobFromAgent() when the agent is down, the socket path is wrong, or curl cannot reach the Unix socket. This is the worker idle-loop, so it will surface immediately at the top of every poll.","commonSituations":"Cloud agent restarted/crashed mid-deployment. Wrong CLOUD_AGENT_SOCKET / config.agent.socket path. Socket file removed or permissions changed. Running a cloud-connection worker on infrastructure that does not provide the Cloud agent.","solutions":["Confirm the worker is running inside Laravel Cloud where the agent socket exists.","Verify config('queue.connections.cloud.agent.socket') matches the actual socket path provided by Cloud.","Restart the deployment / agent process; the socket is recreated on agent startup.","Ensure the PHP user has read/write permissions on the socket file.","Catch AgentUnreachableException in a wrapper worker and back off rather than hot-looping."],"exampleFix":"// before — worker dies on first unreachable poll\nwhile (true) { $queue->requestNextJobFromAgent(); }\n\n// after — back off on agent outages\nuse Illuminate\\Foundation\\Cloud\\AgentUnreachableException;\n\nwhile (true) {\n    try {\n        $job = $queue->requestNextJobFromAgent();\n    } catch (AgentUnreachableException $e) {\n        logger()->warning('Cloud agent unreachable: '.$e->getMessage());\n        sleep(5); // backoff; replace with a real wait primitive\n        continue;\n    }\n}","handlingStrategy":"try-catch","validationCode":"$socket = config('queue.connections.cloud.agent.socket', '/tmp/cloud-agent.sock');\nif (! file_exists($socket) || ! is_readable($socket) || ! is_writable($socket)) {\n    throw new \\RuntimeException('Cloud agent socket unreachable: '.$socket);\n}","typeGuard":"// Infrastructure check, not a type. Detect Cloud runtime before starting a cloud worker.\nfunction cloudAgentReachable(): bool {\n    $s = config('queue.connections.cloud.agent.socket', '/tmp/cloud-agent.sock');\n    return file_exists($s) && is_writable($s);\n}","tryCatchPattern":"use Illuminate\\Foundation\\Cloud\\AgentUnreachableException;\n\ntry {\n    $job = $queue->requestNextJobFromAgent();\n} catch (AgentUnreachableException $e) {\n    // back off (use a real wait primitive), alert, and retry the poll\n    report($e);\n}","preventionTips":["Run cloud-connection workers only inside Laravel Cloud.","Verify the agent socket path matches config before starting the worker.","Wrap the worker loop to back off on AgentUnreachableException rather than hot-looping."],"tags":["laravel-cloud","queue","socket","network","agent-unreachable"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}