benbjohnson/litestream · error

too many arguments

Error message

too many arguments

What it means

`litestream restore` accepts at most one positional argument — either a database path or a replica URL. If more than one positional argument is supplied on the command line, the command rejects it with this plain error instead of guessing which target you meant. It is pure argument-count validation performed in Restore's Run before any work starts.

Source

Thrown at cmd/litestream/restore.go:51

	ifDBNotExists := fs.Bool("if-db-not-exists", false, "")
	ifReplicaExists := fs.Bool("if-replica-exists", false, "")
	timestampStr := fs.String("timestamp", "", "timestamp")
	dryRun := fs.Bool("dry-run", false, "print restore plan without writing")
	force := fs.Bool("force", false, "overwrite existing output database")
	jsonOutput := fs.Bool("json", false, "output raw JSON")
	fs.BoolVar(&opt.Follow, "f", false, "follow mode")
	fs.DurationVar(&opt.FollowInterval, "follow-interval", opt.FollowInterval, "polling interval for follow mode")
	integrityCheck := fs.String("integrity-check", "none", "post-restore integrity check: none, quick, or full")
	fs.Usage = c.Usage
	if err := fs.Parse(args); err != nil {
		return err
	} else if fs.NArg() == 0 || fs.Arg(0) == "" {
		return &usageError{
			message: "database path or replica URL required",
			hint:    "litestream restore -o /path/to/db s3://bucket/prefix",
		}
	} else if fs.NArg() > 1 {
		return fmt.Errorf("too many arguments")
	}

	logOutput := os.Stdout
	if *jsonOutput {
		logOutput = os.Stderr
	}
	internal.InitLog(logOutput, "INFO", "text", false)

	// When follow mode is enabled, set up signal handling so Ctrl+C stops
	// the follow loop cleanly.
	if opt.Follow {
		ch := signalChan()
		cancelCtx, cancel := context.WithCancel(ctx)
		go func() {
			select {
			case <-ch:
				cancel()
			case <-cancelCtx.Done():

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Use exactly one positional arg: either the db path (with -config if needed) or the replica URL, never both
2. Quote paths containing spaces: litestream restore -o out.db "/path/with space/db.sqlite"
3. If you need to restore from a specific replica of a configured db, use the URL form alone: litestream restore -o out.db s3://bucket/prefix

Example fix

// before
litestream restore -o out.db /var/lib/db/app.db s3://bucket/prefix
// after
litestream restore -o out.db s3://bucket/prefix

args := flag.Args()
if len(args) > 1 {
    return fmt.Errorf("restore takes exactly one positional arg (db path or replica URL), got %d", len(args))
}

When it happens

Trigger: `litestream restore -o out.db /path/to/db s3://bucket/prefix` or any invocation with two or more positional args, e.g. passing both a local db path and a replica URL together, or unquoted paths containing spaces.

Common situations: Users combining the two targeting styles (path + URL) in one command; shell word-splitting of unquoted paths with spaces; copy-pasting example commands that include both forms.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• too many arguments
• too many arguments
• must specify at least one replica URL for %s
• invalid -integrity-check value: %s

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