{"id":"169d1eab2c0793a0","repo":"laravel/framework","slug":"the-laravel-cloud-agent-returned-http-e-respons","errorCode":null,"errorMessage":"The Laravel Cloud agent returned HTTP {$e->response->status()} from POST /result.","messagePattern":"The Laravel Cloud agent returned HTTP (.+?) from POST /result\\.","errorType":"exception","errorClass":"AgentUnreachableException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Foundation/Cloud/Queue.php","lineNumber":309,"sourceCode":"    {\n        try {\n            $this->agentRequest()\n                ->timeout(10)\n                ->throw()\n                ->retry(3, 100, fn ($exception) => $exception instanceof ConnectionException)\n                ->post('/result', array_filter([\n                    'messageId' => $messageId,\n                    'receiptHandle' => $receiptHandle,\n                    'status' => $status,\n                    'delay' => $delay,\n                ], fn ($value) => $value !== null));\n        } catch (ConnectionException $e) {\n            throw new AgentUnreachableException(\n                'The Laravel Cloud agent runtime socket is unreachable.', previous: $e\n            );\n        } catch (RequestException $e) {\n            if ($e->response->serverError()) {\n                throw new AgentUnreachableException(\n                    \"The Laravel Cloud agent returned HTTP {$e->response->status()} from POST /result.\", previous: $e\n                );\n            }\n\n            throw $e;\n        }\n    }\n\n    /**\n     * Get a pending HTTP request bound to the agent's Unix runtime socket.\n     *\n     * @return \\Illuminate\\Http\\Client\\PendingRequest\n     */\n    protected function agentRequest()\n    {\n        return Http::withoutGlobalConfiguration(\n            fn () => Http::baseUrl('http://localhost')->withOptions([\n                'curl' => [","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Foundation/Cloud/Queue.php#L291-L327","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Inspect the agent logs around the 5xx to identify the upstream cause.","Restart/redeploy the agent; transient 5xx often clears.","Ensure agent and SDK versions are compatible.","Catch AgentUnreachableException and treat the job as not-acked (it may redeliver); log for reconciliation."],"exampleFix":"// before\n$queue->reportJobStatusToAgent($id, $receipt, 'success');\n\n// after\nuse Illuminate\\Foundation\\Cloud\\AgentUnreachableException;\n\ntry {\n    $queue->reportJobStatusToAgent($id, $receipt, 'success');\n} catch (AgentUnreachableException $e) {\n    // not acked — anticipate a redelivery and handle idempotently\n    report($e);\n}","handlingStrategy":"try-catch","validationCode":"// No deterministic pre-check for a server-side 5xx; you can short-circuit on a failed health probe first.\n// See errorIndex 289 validationCode for a /health probe pattern.","typeGuard":"// Not type-based. Use the exception type to branch.\nfunction isAgentServer\\Error(\\Throwable $e): bool {\n    return $e instanceof \\Illuminate\\Foundation\\Cloud\\AgentUnreachableException\n        && str_contains($e->getMessage(), 'POST /result');\n}","tryCatchPattern":"use Illuminate\\Foundation\\Cloud\\AgentUnreachableException;\n\ntry {\n    $queue->reportJobStatusToAgent($id, $receipt, 'success');\n} catch (AgentUnreachableException $e) {\n    if (str_contains($e->getMessage(), 'POST /result')) {\n        // not acked — anticipate redelivery; report for reconciliation\n        report($e);\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Make job handlers idempotent so an un-acked result is safe to redeliver.","Watch agent logs for 5xx patterns; persistent 5xx often indicates a version or upstream-SQS issue.","Keep agent and SDK versions aligned."],"tags":["laravel-cloud","queue","agent-unreachable","http-status","result-report","server-error"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}