{"record":{"id":"ae30326c02591668","repo":"benbjohnson/litestream","slug":"failed-to-connect-to-control-socket-w-ae3032","errorCode":null,"errorMessage":"failed to connect to control socket: %w","messagePattern":"failed to connect to control socket: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/litestream/register.go","lineNumber":74,"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.RegisterDatabaseRequest{\n\t\tPath:       dbPath,\n\t\tReplicaURL: replicaURL,\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/register\", \"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(\"register failed: %s\", errResp.Error)\n\t\t}\n\t\treturn fmt.Errorf(\"register failed: %s\", string(body))\n\t}\n\n\tvar result litestream.RegisterDatabaseResponse\n\tif err := json.Unmarshal(body, &result); err != nil {","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/register.go#L56-L92","documentation":"The register command talks to the litestream daemon over a Unix control socket (custom DialContext dialing 'unix' at -socket path, default /var/run/litestream.sock). If client.Post fails — socket missing, daemon not running, socket disabled in config, permission denied, or the -timeout elapsed — the error is wrapped as 'failed to connect to control socket'.","triggerScenarios":"Running `litestream register` while the litestream server is not running; the IPC socket is disabled (default: socket.enabled not set to true); wrong -socket path; timeout too small; permissions on the socket file block connecting.","commonSituations":"User forgot to enable `socket.enabled: true` in the litestream config and restart the daemon; daemon crashed or was restarted; running as a different user than the socket owner; SELinux/AppArmor blocking /var/run/litestream.sock.","solutions":["Start the litestream daemon and enable the control socket with `socket.enabled: true` in the config, then restart it","Confirm the socket path: `ls -l /var/run/litestream.sock` (or your -socket value) and pass -socket if it differs","Check permissions — run the command as the same user that owns the socket or adjust socket ownership","Increase -timeout if the daemon is slow to answer (e.g. -timeout 120)","Check daemon logs for crashes and verify the daemon was started with the same config"],"exampleFix":"// before (config.yml)\n// (no socket section)\n// after (config.yml)\nsocket:\n  enabled: true","handlingStrategy":"retry","validationCode":"if [ ! -S /var/run/litestream.sock ]; then echo \"control socket missing: enable socket.enabled in config and start the daemon\"; exit 1; fi","typeGuard":null,"tryCatchPattern":"err := registerCmd.Run(ctx, args)\nif err != nil && strings.Contains(err.Error(), \"failed to connect to control socket\") {\n    // backoff and retry a bounded number of times\n    time.Sleep(2 * time.Second)\n    err = registerCmd.Run(ctx, args)\n}","preventionTips":["Enable `socket.enabled: true` in the daemon config and restart before registering","Check the socket file exists with ls -l before invoking","Run the CLI as the user that owns the socket","Use a generous -timeout (30s default is fine)"],"tags":["network","unix-socket","ipc","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-14T05:17:10.506Z"}