benbjohnson/litestream · error

too many arguments

Error message

too many arguments

What it means

`litestream start <dbpath>` sends a start command over the IPC control socket and therefore accepts exactly one positional argument: the database path. Run returns the plain error 'too many arguments' when fs.NArg() > 1. This is a usage error enforced by the command's flag parser before any socket work happens.

Source

Thrown at cmd/litestream/start.go:38

// Run executes the start command.
func (c *StartCommand) Run(ctx context.Context, args []string) error {
	fs := flag.NewFlagSet("litestream-start", flag.ContinueOnError)
	timeout := fs.Int("timeout", 30, "timeout in seconds")
	socketPath := fs.String("socket", "/var/run/litestream.sock", "control socket path")
	jsonOutput := fs.Bool("json", false, "output raw JSON")
	fs.Usage = c.Usage
	if err := fs.Parse(args); err != nil {
		return err
	}

	if fs.NArg() == 0 {
		return &usageError{
			message: "database path required",
			hint:    "litestream start /path/to/db",
		}
	}
	if fs.NArg() > 1 {
		return fmt.Errorf("too many arguments")
	}

	dbPath := fs.Arg(0)

	// 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.StartRequest{
		Path:    dbPath,
		Timeout: *timeout,

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Pass exactly one database path and quote it if it contains spaces: `litestream start "/var/lib/My App/db.sqlite"`
2. Run one `litestream start` per database instead of passing multiple paths
3. Check for misspelled flags — an unrecognized flag can end up treated as a positional argument
4. Run `litestream start -h` to review the accepted argument form

Example fix

// before
litestream start /var/lib/my app/db.sqlite
// error: too many arguments

// after — quote the path
litestream start "/var/lib/my app/db.sqlite"

// shell pre-flight: assert exactly one positional arg and quote it
[ $# -eq 1 ] || { echo "usage: litestream start <dbpath>"; exit 2; }
litestream start "$1"

When it happens

Trigger: Invoking `litestream start` with more than one positional argument, e.g. quoting mistakes like `litestream start /var/lib/my db.sqlite` (unquoted space), passing extra paths, or trailing stray tokens after the db path.

Common situations: Paths containing spaces passed without quotes; copy-pasting a command line with multiple databases (start handles one db at a time); accidentally appending flags that were misspelled so they are parsed as positional args.

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

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

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