benbjohnson/litestream · error

start failed: %s

Error message

start failed: %s

What it means

The daemon returned a non-200 status for the /start request and its body parsed as a litestream.ErrorResponse containing an Error message; the CLI surfaces that server-side message prefixed with 'start failed:'. The actual cause is in the suffix text, which comes from the daemon's own replication-start logic.

Source

Thrown at cmd/litestream/start.go:77

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

	resp, err := client.Post("http://localhost/start", "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("start failed: %s", errResp.Error)
		}
		return fmt.Errorf("start failed: %s", string(body))
	}

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

	confirmation := StartStopResult{
		Status: result.Status,
		DBPath: result.Path,
		State:  "running",
		TXID:   result.TXID,
		Socket: *socketPath,
	}
	if err := printStartStopResult(confirmation, *jsonOutput); err != nil {
		return err

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Read the text after 'start failed:' — it is the daemon's own error message
2. Verify the DB path is registered in the daemon's config and matches exactly
3. If already running, use `litestream status` instead of starting again
4. Check daemon logs for the underlying replication error
5. Run `litestream reset <db>` if the daemon reports corrupted local LTX state

// confirm DB is registered before starting:
// litestream status /path/to/db  → must list the database

if err != nil {
    var msg string
    if _, perr := fmt.Sscanf(err.Error(), "start failed: %s", &msg); perr == nil {
        log.Printf("daemon rejected start: %s", msg)
    }
}

When it happens

Trigger: POSTing /start to the control socket and the daemon rejects the request — e.g. the database path is not registered with the daemon, the database is already running, or replication failed to start (LTX errors, storage unavailable).

Common situations: Typo'd DB path not registered in the daemon config; database already replicating (duplicate start); replica storage credentials invalid so replication can't start; database locked or WAL error server-side.

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

• register failed: %s
• info failed: %s
• failed to connect to control socket: %w
• must specify at least one replica URL for %s
• too many arguments

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