What causes "timeout must be greater than 0" in benbjohnson/litestream?

Omit the -timeout flag entirely to use the default of 30 seconds

timeout must be greater than 0

Error message

timeout must be greater than 0

What it means

litestream register validates the -timeout flag before creating its HTTP client for the control socket. A timeout of zero or negative seconds cannot be used as an HTTP client timeout (a zero http.Client.Timeout means no timeout, which is dangerous), so the command rejects it upfront with this plain error.

Source

Thrown at cmd/litestream/register.go:46

	}

	if fs.NArg() == 0 {
		return &usageError{
			message: "database path required",
			hint:    "litestream register -replica s3://bucket/prefix /path/to/db",
		}
	}
	if fs.NArg() > 1 {
		return fmt.Errorf("too many arguments")
	}
	if *replicaFlag == "" {
		return &usageError{
			message: "-replica is required",
			hint:    "litestream register -replica s3://bucket/prefix /path/to/db",
		}
	}
	if *timeout <= 0 {
		return fmt.Errorf("timeout must be greater than 0")
	}

	dbPath := fs.Arg(0)
	replicaURL := *replicaFlag

	// Create HTTP client that connects via Unix socket with timeout.
	clientTimeout := time.Duration(*timeout) * time.Second
	client := &http.Client{
		Timeout: clientTimeout,
		Transport: &http.Transport{
			DialContext: func(_ context.Context, _, _ string) (net.Conn, error) {
				return net.DialTimeout("unix", *socketPath, clientTimeout)
			},
		},
	}

	req := litestream.RegisterDatabaseRequest{
		Path:       dbPath,

View on GitHub (pinned to 4ed7a308f6)

Solutions

Omit the -timeout flag entirely to use the default of 30 seconds
Pass a positive integer, e.g. -timeout 60
If the value is computed, guard it: only pass -timeout when the computed value is > 0

Example fix

// before
litestream register -timeout $TIMEOUT -replica s3://bucket/db /path/db
// after
TIMEOUT=${TIMEOUT:-30}
if [ "$TIMEOUT" -le 0 ]; then TIMEOUT=30; fi
litestream register -timeout "$TIMEOUT" -replica s3://bucket/db /path/db

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$TIMEOUT" ] || [ "$TIMEOUT" -le 0 ]; then TIMEOUT=30; fi
litestream register -timeout "$TIMEOUT" -replica "$REPLICA" "$DB"

Prevention

Never pass timeout=0 expecting 'unlimited' — omit the flag instead
Default numeric variables with ${VAR:-30} before interpolation
Validate computed timeouts in shell wrappers before invoking

When it happens

Trigger: Running `litestream register -timeout 0 ...` or `-timeout` with a negative value (e.g. scripted invocations that compute the timeout from a variable which defaults to 0, or `-timeout -1` meant as an 'infinite' flag).

Common situations: CI scripts that interpolate an unset environment variable into the -timeout flag (expanding to 0); users expecting timeout=0 to mean 'no timeout' as it does for net/http; copy-paste typos in shell wrappers.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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