laravel/framework · error · AgentUnreachableException

The Laravel Cloud agent returned HTTP {$response->status()}

Error message

The Laravel Cloud agent returned HTTP {$response->status()} from GET /next.

What it means

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.

Source

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

     */
    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.'
            );
        }

        return $data;
    }

    /**
     * Report a job's terminal outcome back to the agent (POST /result).
     *
     * @throws \Illuminate\Http\Client\RequestException
     * @throws \Illuminate\Foundation\Cloud\AgentUnreachableException

View on GitHub (pinned to bd6b5437e6)

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.

Example fix

// before
$job = $queue->requestNextJobFromAgent();

// after
use Illuminate\Foundation\Cloud\AgentUnreachableException;

try {
    $job = $queue->requestNextJobFromAgent();
} catch (AgentUnreachableException $e) {
    report($e);
    // back off and retry the poll; surface to monitoring
    throw $e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check is limited; you can ping the agent before the long poll:
use Illuminate\Support\Facades\Http;

$resp = Http::withOptions(['curl' => [CURLOPT_UNIX_SOCKET_PATH => config('queue.connections.cloud.agent.socket', '/tmp/cloud-agent.sock')]])->get('http://localhost/health');
if (! $resp->ok()) {
    throw new \RuntimeException('Cloud agent health check failed: '.$resp->status());
}

Type guard

// Not type-based. Treat any AgentUnreachableException as transient-or-fatal based on monitoring.

Try / catch

use Illuminate\Foundation\Cloud\AgentUnreachableException;

try {
    $job = $queue->requestNextJobFromAgent();
} catch (AgentUnreachableException $e) {
    if (str_contains($e->getMessage(), 'returned HTTP')) {
        report($e); // agent answered with an error — back off, escalate if persistent
    } else {
        throw $e;
    }
}

Prevention

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.

When it happens

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

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

Related errors

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