laravel/framework · error · AgentUnreachableException

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

Error message

The Laravel Cloud agent returned HTTP {$e->response->status()} from POST /result.

What it means

Thrown as AgentUnreachableException from Queue::reportJobStatusToAgent() when POST /result throws a RequestException with a server-error (5xx) status. The request uses ->throw() so non-2xx raise; the catch block converts server errors to AgentUnreachableException (with the status code in the message) while re-throwing 4xx as-is for the caller. This means the agent received the result but failed to process it.

Source

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

    {
        try {
            $this->agentRequest()
                ->timeout(10)
                ->throw()
                ->retry(3, 100, fn ($exception) => $exception instanceof ConnectionException)
                ->post('/result', array_filter([
                    'messageId' => $messageId,
                    'receiptHandle' => $receiptHandle,
                    'status' => $status,
                    'delay' => $delay,
                ], fn ($value) => $value !== null));
        } catch (ConnectionException $e) {
            throw new AgentUnreachableException(
                'The Laravel Cloud agent runtime socket is unreachable.', previous: $e
            );
        } catch (RequestException $e) {
            if ($e->response->serverError()) {
                throw new AgentUnreachableException(
                    "The Laravel Cloud agent returned HTTP {$e->response->status()} from POST /result.", previous: $e
                );
            }

            throw $e;
        }
    }

    /**
     * Get a pending HTTP request bound to the agent's Unix runtime socket.
     *
     * @return \Illuminate\Http\Client\PendingRequest
     */
    protected function agentRequest()
    {
        return Http::withoutGlobalConfiguration(
            fn () => Http::baseUrl('http://localhost')->withOptions([
                'curl' => [

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Inspect the agent logs around the 5xx to identify the upstream cause.
2. Restart/redeploy the agent; transient 5xx often clears.
3. Ensure agent and SDK versions are compatible.
4. Catch AgentUnreachableException and treat the job as not-acked (it may redeliver); log for reconciliation.

Example fix

// before
$queue->reportJobStatusToAgent($id, $receipt, 'success');

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

try {
    $queue->reportJobStatusToAgent($id, $receipt, 'success');
} catch (AgentUnreachableException $e) {
    // not acked — anticipate a redelivery and handle idempotently
    report($e);
}

// No deterministic pre-check for a server-side 5xx; you can short-circuit on a failed health probe first.
// See errorIndex 289 validationCode for a /health probe pattern.

// Not type-based. Use the exception type to branch.
function isAgentServer\Error(\Throwable $e): bool {
    return $e instanceof \Illuminate\Foundation\Cloud\AgentUnreachableException
        && str_contains($e->getMessage(), 'POST /result');
}

use Illuminate\Foundation\Cloud\AgentUnreachableException;

try {
    $queue->reportJobStatusToAgent($id, $receipt, 'success');
} catch (AgentUnreachableException $e) {
    if (str_contains($e->getMessage(), 'POST /result')) {
        // not acked — anticipate redelivery; report for reconciliation
        report($e);
    } else {
        throw $e;
    }
}

When it happens

Trigger: POST /result returns 5xx — the agent is up but errored processing the job-result ack. Reached after every job on the cloud connection completes/fails. Distinct from [291] which is a connection failure (no response at all).

Common situations: Agent-side bug or overloaded downstream (e.g. SQS delete failing inside the agent). Agent restart returning 503. Version mismatch where the result payload schema changed. Transient upstream (SQS) outage propagated through the agent.

Related errors

• The Laravel Cloud agent returned HTTP {$response->status()}
• The Laravel Cloud agent runtime socket is unreachable.
• The Laravel Cloud agent returned a non-array body from GET /
• The failed job provider does not have a configured queue
• Managed queue [{$name}] does not exist.

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