laravel/framework · critical · RuntimeException

Failed connecting to the socket: {$errorMessage} [{$errorCod

Error message

Failed connecting to the socket: {$errorMessage} [{$errorCode}]

What it means

Thrown by Foundation\Cloud\Events::connect() when stream_socket_client() returns false while connecting to the Laravel Cloud events socket. The message includes the underlying PHP error message and code (e.g. connection refused, no such file). This is infrastructure-level: the Cloud runtime agent that emits events is unreachable. The class only exists/operates inside Laravel Cloud managed runtime.

Source

Thrown at src/Illuminate/Foundation/Cloud/Events.php:140

            $this->connect();
        }
    }

    /**
     * Connect the socket.
     */
    protected function connect(): void
    {
        $socket = stream_socket_client(
            address: $this->address,
            error_code: $errorCode,
            error_message: $errorMessage,
            timeout: 2,
            flags: STREAM_CLIENT_CONNECT | STREAM_CLIENT_PERSISTENT,
        );

        if ($socket === false) {
            throw new RuntimeException("Failed connecting to the socket: {$errorMessage} [{$errorCode}]");
        }

        if (! stream_set_timeout($socket, 2)) {
            $e = new RuntimeException($this->withSocketMetaData('Failed configuring socket timeout'));

            $this->disconnect();

            throw $e;
        }

        $this->socket = $socket;
    }

    /**
     * Determine if the socket is connected.
     */
    protected function connected(): bool
    {

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Confirm the code is actually executing inside Laravel Cloud managed runtime; the Cloud agent only exists there.
2. Verify the configured socket path/address is correct and the socket file exists and is readable/writable by the PHP process.
3. Ensure the Cloud agent process is up (restart the deployment / agent) before retrying.
4. Guard Cloud-only code with an environment check (e.g. env('LARAVEL_CLOUD')) before invoking Events.
5. Wrap emit calls in try/catch and degrade gracefully if event delivery is non-critical.

Example fix

// before
$events->emit(['_cloud_event' => 'failed_job', ...]);

// after
if (app()->runningUnitTests() || ! env('LARAVEL_CLOUD')) {
    return; // skip outside Cloud runtime
}
try {
    $events->emit($payload);
} catch (\RuntimeException $e) {
    logger()->warning('Cloud events socket unavailable: '.$e->getMessage());
}

use Illuminate\Support\Facades\Http;

$socket = config('cloud.events.socket', '/tmp/cloud-agent.sock');
if (! file_exists($socket) || ! is_writable($socket)) {
    return; // do not attempt emit; agent socket not available
}

// This is infrastructure, not a type. Guard by environment:
function isCloudRuntime(): bool {
    return (bool) env('LARAVEL_CLOUD') || file_exists('/tmp/cloud-agent.sock');
}

try {
    $events->emit($payload);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'Failed connecting to the socket')) {
        logger()->warning('Cloud events socket down: '.$e->getMessage());
        return; // degrade gracefully if event delivery is non-critical
    }
    throw $e;
}

When it happens

Trigger: Calling event emission (Events::emit()) when the configured socket address is wrong, the agent process is not running, the Unix socket file is missing, or the network path is blocked. Surfaces during failed-job event emission, custom Cloud event publishes, or any Foundation\Cloud service that wires through Events.

Common situations: Running Cloud-aware code outside Laravel Cloud (e.g. on a normal server or local dev) where the agent socket does not exist. Socket path misconfiguration in config. Agent crash/restart mid-request. Permission denied on the socket file.

Related errors

• The Laravel Cloud agent runtime socket is unreachable.
• The Laravel Cloud agent returned HTTP {$response->status()}
• Ably error: %s
• Pusher error: %s.
• Redis error: %s.

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