benbjohnson/litestream · error

register failed: %s

Error message

register failed: %s

What it means

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.

Source

Thrown at cmd/litestream/register.go:86

	if err != nil {
		return fmt.Errorf("failed to marshal request: %w", err)
	}

	resp, err := client.Post("http://localhost/register", "application/json", bytes.NewReader(reqBody))
	if err != nil {
		return fmt.Errorf("failed to connect to control socket: %w", err)
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return fmt.Errorf("failed to read response: %w", err)
	}

	if resp.StatusCode != http.StatusOK {
		var errResp litestream.ErrorResponse
		if err := json.Unmarshal(body, &errResp); err == nil && errResp.Error != "" {
			return fmt.Errorf("register failed: %s", errResp.Error)
		}
		return fmt.Errorf("register failed: %s", string(body))
	}

	var result litestream.RegisterDatabaseResponse
	if err := json.Unmarshal(body, &result); err != nil {
		return fmt.Errorf("failed to parse response: %w", err)
	}

	confirmation := RegisterResult{
		Status:  result.Status,
		DBPath:  result.Path,
		Replica: replicaURL,
		Socket:  *socketPath,
	}
	if *jsonOutput {
		output, err := json.MarshalIndent(confirmation, "", "  ")
		if err != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Read the message after 'register failed:' — it is the server's own error text and points to the real cause
2. Verify the DB path exists and the replica URL scheme is valid (s3://, file:/// etc.)
3. Check the daemon's log output for the corresponding server-side error
4. If the DB was already registered and is in a bad state, consider `litestream reset` per project docs

[ -f "$DB" ] || { echo "db path does not exist: $DB"; exit 1; }
case "$REPLICA" in s3://*|file://*) ;; *) echo "unsupported replica URL scheme"; exit 1;; esac

if err := registerCmd.Run(ctx, args); err != nil {
    var serverMsg string
    if _, e := fmt.Sscanf(err.Error(), "register failed: %s", &serverMsg); e == nil {
        log.Fatalf("server rejected registration: %s", serverMsg)
    }
}

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• start failed: %s
• info failed: %s
• failed to connect to control socket: %w
• too many arguments
• failed to marshal request: %w

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/18cf7c5cec0c8075. Report an issue: GitHub.