laravel/framework · critical · AgentUnreachableException

The Laravel Cloud agent runtime socket is unreachable.

Error message

The Laravel Cloud agent runtime socket is unreachable.

What it means

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`.

Source

Thrown at src/Illuminate/Foundation/Cloud/Queue.php:260

                $messageId, $receiptHandle, $status, $delay
            ),
            $this->config['connection']['overflow'] ?? [],
        );
    }

    /**
     * Long-poll the agent's runtime socket (GET /next) for the next job.
     *
     * @throws \Illuminate\Foundation\Cloud\AgentUnreachableException
     */
    protected function requestNextJobFromAgent(): ?array
    {
        try {
            $response = $this->agentRequest()
                ->timeout(65)
                ->get('/next');
        } catch (ConnectionException $e) {
            throw new AgentUnreachableException(
                'The Laravel Cloud agent runtime socket is unreachable.', previous: $e
            );
        }

        if ($response->status() === 204) {
            return null;
        }

        if (! $response->ok()) {
            throw new AgentUnreachableException(
                "The Laravel Cloud agent returned HTTP {$response->status()} from GET /next."
            );
        }

        if (! is_array($data = $response->json())) {
            throw new AgentUnreachableException(
                'The Laravel Cloud agent returned a non-array body from GET /next.'
            );

View on GitHub (pinned to bd6b5437e6)

Solutions

  1. Confirm the worker is running inside Laravel Cloud where the agent socket exists.
  2. Verify config('queue.connections.cloud.agent.socket') matches the actual socket path provided by Cloud.
  3. Restart the deployment / agent process; the socket is recreated on agent startup.
  4. Ensure the PHP user has read/write permissions on the socket file.
  5. Catch AgentUnreachableException in a wrapper worker and back off rather than hot-looping.

Example fix

// before — worker dies on first unreachable poll
while (true) { $queue->requestNextJobFromAgent(); }

// after — back off on agent outages
use Illuminate\Foundation\Cloud\AgentUnreachableException;

while (true) {
    try {
        $job = $queue->requestNextJobFromAgent();
    } catch (AgentUnreachableException $e) {
        logger()->warning('Cloud agent unreachable: '.$e->getMessage());
        sleep(5); // backoff; replace with a real wait primitive
        continue;
    }
}
Defensive patterns

Strategy: try-catch

Validate before calling

$socket = config('queue.connections.cloud.agent.socket', '/tmp/cloud-agent.sock');
if (! file_exists($socket) || ! is_readable($socket) || ! is_writable($socket)) {
    throw new \RuntimeException('Cloud agent socket unreachable: '.$socket);
}

Type guard

// Infrastructure check, not a type. Detect Cloud runtime before starting a cloud worker.
function cloudAgentReachable(): bool {
    $s = config('queue.connections.cloud.agent.socket', '/tmp/cloud-agent.sock');
    return file_exists($s) && is_writable($s);
}

Try / catch

use Illuminate\Foundation\Cloud\AgentUnreachableException;

try {
    $job = $queue->requestNextJobFromAgent();
} catch (AgentUnreachableException $e) {
    // back off (use a real wait primitive), alert, and retry the poll
    report($e);
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/bb1479ac283d2c63.json. Report an issue: GitHub.