laravel/framework · error · AgentUnreachableException

The Laravel Cloud agent returned a non-array body from GET /

Error message

The Laravel Cloud agent returned a non-array body from GET /next.

What it means

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.

Source

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

                ->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
     */
    protected function reportJobStatusToAgent(string $messageId, ?string $receiptHandle, string $status, ?int $delay = null): void
    {
        try {
            $this->agentRequest()
                ->timeout(10)

View on GitHub (pinned to bd6b5437e6)

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.

Example fix

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

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

try {
    $job = $queue->requestNextJobFromAgent();
} catch (AgentUnreachableException $e) {
    report($e);
    // surface to ops — a non-array body is an agent contract violation
    throw $e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Cannot fully pre-validate the body shape without making the call, but you can version-check:
if (config('cloud.agent.version') !== config('cloud.sdk.expected_version')) {
    throw new \RuntimeException('Cloud agent/SDK version mismatch — body contract may be broken.');
}

Type guard

// After a successful raw call, you could validate shape; the framework already does is_array() and throws.
function isValidNextJobBody(mixed $body): bool { return is_array($body); }

Try / catch

use Illuminate\Foundation\Cloud\AgentUnreachableException;

try {
    $job = $queue->requestNextJobFromAgent();
} catch (AgentUnreachableException $e) {
    if (str_contains($e->getMessage(), 'non-array body')) {
        // agent contract violation — capture diagnostics, escalate as agent bug
        report($e);
    }
}

Prevention

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.

When it happens

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

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

Related errors

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