{"id":"7c3c92a5333946f6","repo":"laravel/framework","slug":"the-laravel-cloud-agent-returned-a-non-array-body","errorCode":null,"errorMessage":"The Laravel Cloud agent returned a non-array body from GET /next.","messagePattern":"The Laravel Cloud agent returned a non-array body from GET /next\\.","errorType":"exception","errorClass":"AgentUnreachableException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Foundation/Cloud/Queue.php","lineNumber":276,"sourceCode":"                ->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            );\n        }\n\n        return $data;\n    }\n\n    /**\n     * Report a job's terminal outcome back to the agent (POST /result).\n     *\n     * @throws \\Illuminate\\Http\\Client\\RequestException\n     * @throws \\Illuminate\\Foundation\\Cloud\\AgentUnreachableException\n     */\n    protected function reportJobStatusToAgent(string $messageId, ?string $receiptHandle, string $status, ?int $delay = null): void\n    {\n        try {\n            $this->agentRequest()\n                ->timeout(10)","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Foundation/Cloud/Queue.php#L258-L294","documentation":"Thrown as AgentUnreachableException from Queue::requestNextJobFromAgent() when the JSON body of a successful GET /next is not an array. The agent should respond either 204 (no job) or 200 with a JSON object/array describing the job; is_array($response->json()) returning false means the contract is broken (e.g. a JSON scalar, null, or malformed shape). The worker refuses to guess and aborts.","triggerScenarios":"The Cloud agent returns a 2xx with a non-array JSON body (e.g. a bare string, number, null, or an object that json_decode returns as object). Triggered in the worker poll loop on the cloud connection.","commonSituations":"Agent/SDK version mismatch where the response schema changed. Agent bug returning a wrong envelope. A proxy or debug middleware injecting a non-conforming body. Malformed agent response during a partial deploy.","solutions":["Verify the Cloud agent version matches the SDK version expected by this framework release.","Restart/redeploy the agent to clear transient corruption.","Capture the raw response body for diagnosis (log it before the throw by extending the class) and report to the Cloud integration maintainers.","Handle AgentUnreachableException with backoff; if it persists, escalate as an agent bug."],"exampleFix":"// before\n$job = $queue->requestNextJobFromAgent();\n\n// after\nuse Illuminate\\Foundation\\Cloud\\AgentUnreachableException;\n\ntry {\n    $job = $queue->requestNextJobFromAgent();\n} catch (AgentUnreachableException $e) {\n    report($e);\n    // surface to ops — a non-array body is an agent contract violation\n    throw $e;\n}","handlingStrategy":"try-catch","validationCode":"// Cannot fully pre-validate the body shape without making the call, but you can version-check:\nif (config('cloud.agent.version') !== config('cloud.sdk.expected_version')) {\n    throw new \\RuntimeException('Cloud agent/SDK version mismatch — body contract may be broken.');\n}","typeGuard":"// After a successful raw call, you could validate shape; the framework already does is_array() and throws.\nfunction isValidNextJobBody(mixed $body): bool { return is_array($body); }","tryCatchPattern":"use Illuminate\\Foundation\\Cloud\\AgentUnreachableException;\n\ntry {\n    $job = $queue->requestNextJobFromAgent();\n} catch (AgentUnreachableException $e) {\n    if (str_contains($e->getMessage(), 'non-array body')) {\n        // agent contract violation — capture diagnostics, escalate as agent bug\n        report($e);\n    }\n}","preventionTips":["Pin compatible Cloud agent and SDK versions.","Capture raw responses in staging to catch schema regressions early.","Alert on repeated 'non-array body' errors — they indicate an agent bug."],"tags":["laravel-cloud","queue","agent-unreachable","json","contract-violation"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}