{"record":{"id":"18cf7c5cec0c8075","repo":"benbjohnson/litestream","slug":"register-failed-s","errorCode":null,"errorMessage":"register failed: %s","messagePattern":"register failed: (.+?)","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/register.go","lineNumber":86,"sourceCode":"\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 {\n\t\treturn fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\tconfirmation := RegisterResult{\n\t\tStatus:  result.Status,\n\t\tDBPath:  result.Path,\n\t\tReplica: replicaURL,\n\t\tSocket:  *socketPath,\n\t}\n\tif *jsonOutput {\n\t\toutput, err := json.MarshalIndent(confirmation, \"\", \"  \")\n\t\tif err != nil {","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/register.go#L68-L104","documentation":"When the control socket returns a non-200 status, the command tries to decode an ErrorResponse JSON body and surface its Error field as 'register failed: <server message>'. This is the server-side rejection message propagated to the CLI — the actual cause lives on the daemon, in the wrapped text.","triggerScenarios":"The /register handler rejects the request: database path not found or invalid, replica URL unparseable/unsupported scheme, database already registered with a conflicting replica, or internal daemon error returning a JSON error payload.","commonSituations":"Typo in DB path; replica URL with a scheme the daemon doesn't support; registering the same DB twice with different settings; daemon-side storage misconfiguration (bad S3 credentials).","solutions":["Read the message after 'register failed:' — it is the server's own error text and points to the real cause","Verify the DB path exists and the replica URL scheme is valid (s3://, file:/// etc.)","Check the daemon's log output for the corresponding server-side error","If the DB was already registered and is in a bad state, consider `litestream reset` per project docs"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"[ -f \"$DB\" ] || { echo \"db path does not exist: $DB\"; exit 1; }\ncase \"$REPLICA\" in s3://*|file://*) ;; *) echo \"unsupported replica URL scheme\"; exit 1;; esac","typeGuard":null,"tryCatchPattern":"if err := registerCmd.Run(ctx, args); err != nil {\n    var serverMsg string\n    if _, e := fmt.Sscanf(err.Error(), \"register failed: %s\", &serverMsg); e == nil {\n        log.Fatalf(\"server rejected registration: %s\", serverMsg)\n    }\n}","preventionTips":["Validate the DB path exists and the replica URL scheme before registering","Match daemon and CLI versions","Check daemon logs for the server-side cause","Use litestream reset only when local LTX state is corrupted"],"tags":["http","ipc","cli"],"backgroundTag":"http-error-response","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"}