{"id":"1b8a5a197f40819c","repo":"laravel/framework","slug":"failed-connecting-to-the-socket-errormessage","errorCode":null,"errorMessage":"Failed connecting to the socket: {$errorMessage} [{$errorCode}]","messagePattern":"Failed connecting to the socket: (.+?) \\[(.+?)\\]","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"src/Illuminate/Foundation/Cloud/Events.php","lineNumber":140,"sourceCode":"            $this->connect();\n        }\n    }\n\n    /**\n     * Connect the socket.\n     */\n    protected function connect(): void\n    {\n        $socket = stream_socket_client(\n            address: $this->address,\n            error_code: $errorCode,\n            error_message: $errorMessage,\n            timeout: 2,\n            flags: STREAM_CLIENT_CONNECT | STREAM_CLIENT_PERSISTENT,\n        );\n\n        if ($socket === false) {\n            throw new RuntimeException(\"Failed connecting to the socket: {$errorMessage} [{$errorCode}]\");\n        }\n\n        if (! stream_set_timeout($socket, 2)) {\n            $e = new RuntimeException($this->withSocketMetaData('Failed configuring socket timeout'));\n\n            $this->disconnect();\n\n            throw $e;\n        }\n\n        $this->socket = $socket;\n    }\n\n    /**\n     * Determine if the socket is connected.\n     */\n    protected function connected(): bool\n    {","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Foundation/Cloud/Events.php#L122-L158","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the code is actually executing inside Laravel Cloud managed runtime; the Cloud agent only exists there.","Verify the configured socket path/address is correct and the socket file exists and is readable/writable by the PHP process.","Ensure the Cloud agent process is up (restart the deployment / agent) before retrying.","Guard Cloud-only code with an environment check (e.g. env('LARAVEL_CLOUD')) before invoking Events.","Wrap emit calls in try/catch and degrade gracefully if event delivery is non-critical."],"exampleFix":"// before\n$events->emit(['_cloud_event' => 'failed_job', ...]);\n\n// after\nif (app()->runningUnitTests() || ! env('LARAVEL_CLOUD')) {\n    return; // skip outside Cloud runtime\n}\ntry {\n    $events->emit($payload);\n} catch (\\RuntimeException $e) {\n    logger()->warning('Cloud events socket unavailable: '.$e->getMessage());\n}","handlingStrategy":"try-catch","validationCode":"use Illuminate\\Support\\Facades\\Http;\n\n$socket = config('cloud.events.socket', '/tmp/cloud-agent.sock');\nif (! file_exists($socket) || ! is_writable($socket)) {\n    return; // do not attempt emit; agent socket not available\n}","typeGuard":"// This is infrastructure, not a type. Guard by environment:\nfunction isCloudRuntime(): bool {\n    return (bool) env('LARAVEL_CLOUD') || file_exists('/tmp/cloud-agent.sock');\n}","tryCatchPattern":"try {\n    $events->emit($payload);\n} catch (\\RuntimeException $e) {\n    if (str_contains($e->getMessage(), 'Failed connecting to the socket')) {\n        logger()->warning('Cloud events socket down: '.$e->getMessage());\n        return; // degrade gracefully if event delivery is non-critical\n    }\n    throw $e;\n}","preventionTips":["Only invoke Cloud Events inside Laravel Cloud managed runtime.","Verify the configured socket path exists and is writable before emitting.","Treat event emission as best-effort: catch + log rather than crash the request."],"tags":["laravel-cloud","socket","network","events","runtime-exception"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}