{"record":{"id":"97fc89daef41577f","repo":"benbjohnson/litestream","slug":"failed-to-connect-to-control-socket-w-97fc89","errorCode":null,"errorMessage":"failed to connect to control socket: %w","messagePattern":"failed to connect to control socket: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/start.go","lineNumber":65,"sourceCode":"\t\tTransport: &http.Transport{\n\t\t\tDialContext: func(_ context.Context, _, _ string) (net.Conn, error) {\n\t\t\t\treturn net.DialTimeout(\"unix\", *socketPath, clientTimeout)\n\t\t\t},\n\t\t},\n\t}\n\n\treq := litestream.StartRequest{\n\t\tPath:    dbPath,\n\t\tTimeout: *timeout,\n\t}\n\treqBody, err := json.Marshal(req)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to marshal request: %w\", err)\n\t}\n\n\tresp, err := client.Post(\"http://localhost/start\", \"application/json\", bytes.NewReader(reqBody))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to connect to control socket: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\tif resp.StatusCode != http.StatusOK {\n\t\tvar errResp litestream.ErrorResponse\n\t\tif err := json.Unmarshal(body, &errResp); err == nil && errResp.Error != \"\" {\n\t\t\treturn fmt.Errorf(\"start failed: %s\", errResp.Error)\n\t\t}\n\t\treturn fmt.Errorf(\"start failed: %s\", string(body))\n\t}\n\n\tvar result litestream.StartResponse\n\tif err := json.Unmarshal(body, &result); err != nil {","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/start.go#L47-L83","documentation":"The `litestream start` CLI failed to make an HTTP POST to the daemon's control API. The client dials a Unix socket (default /var/run/litestream.sock) via a custom Transport, so any dial error, timeout, or connection reset surfaces here wrapped as 'failed to connect to control socket'. It means the CLI could not reach the running litestream daemon at all — the request never got a response.","triggerScenarios":"Running `litestream start /path/to/db` when the daemon is not running, the -socket path does not match the daemon's socket (IPC socket is disabled by default — must enable socket.enabled: true in config), the socket file was deleted, or the -timeout seconds elapse before the dial/handshake completes.","commonSituations":"Operator forgot to enable the IPC socket in the daemon config or used a non-default -socket path on only one side; daemon crashed or was restarted; running the CLI in a different mount namespace/container than the daemon so /var/run/litestream.sock is absent; socket permission denied for the current user.","solutions":["Verify the litestream daemon is running and was started with socket.enabled: true in its config","Pass -socket with the exact same path the daemon listens on (default /var/run/litestream.sock)","Check the socket file exists and is accessible: ls -l /var/run/litestream.sock","Increase -timeout if the daemon is slow to accept connections","Run the CLI in the same host/container/namespace as the daemon"],"exampleFix":"// before\nlitestream start /path/to/db\n// after\n# start daemon with IPC socket enabled (config: socket.enabled: true), then:\nlitestream start -socket /var/run/litestream.sock -timeout 30 /path/to/db","handlingStrategy":"fallback","validationCode":"if [ ! -S /var/run/litestream.sock ]; then echo 'control socket missing — is the daemon running with socket.enabled: true?'; exit 1; fi","typeGuard":null,"tryCatchPattern":"if err := startCmd.Run(ctx, args); err != nil {\n    if strings.Contains(err.Error(), \"failed to connect to control socket\") {\n        // check daemon health / socket path before surfacing\n    }\n}","preventionTips":["Enable socket.enabled: true in the daemon config before using start/stop commands","Keep the -socket flag value identical on daemon and CLI","Script a health probe against the socket before issuing commands","Run CLI and daemon in the same mount namespace/container"],"tags":["network","ipc","unix-socket","cli"],"backgroundTag":"connection-refused","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}