benbjohnson/litestream · error

unknown command: %s

Error message

unknown command: %s

What it means

The litestream-test CLI dispatches the first positional argument to a known subcommand (load, shrink, validate, version, etc.). If the argument does not match any registered command, Run returns "unknown command: <name>". This is a CLI usage error, and the Main's Usage() output lists the valid commands.

Source

Thrown at cmd/litestream-test/main.go:65

	if fs.NArg() == 0 || fs.Arg(0) == "help" {
		m.Usage()
		return nil
	}

	switch fs.Arg(0) {
	case "populate":
		return (&PopulateCommand{Main: m}).Run(ctx, fs.Args()[1:])
	case "load":
		return (&LoadCommand{Main: m}).Run(ctx, fs.Args()[1:])
	case "shrink":
		return (&ShrinkCommand{Main: m}).Run(ctx, fs.Args()[1:])
	case "validate":
		return (&ValidateCommand{Main: m}).Run(ctx, fs.Args()[1:])
	case "version":
		return (&VersionCommand{Main: m}).Run(ctx, fs.Args()[1:])
	default:
		return fmt.Errorf("unknown command: %s", fs.Arg(0))
	}
}

func (m *Main) Usage() {
	fmt.Fprintln(m.Stdout, `
litestream-test is a testing harness for Litestream database replication.

Usage:

	litestream-test <command> [arguments]

Commands:

	populate    Quickly populate a database to a target size
	load        Generate continuous load on a database
	shrink      Shrink a database by deleting data
	validate    Validate replication integrity
	version     Show version information

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Run `litestream-test` with no arguments to print usage and use an exact subcommand name from the list.
2. Fix the typo in the subcommand name.
3. Check `litestream-test version` / rebuild from the expected revision if you expect a subcommand that is not present in this build.

Example fix

// before
litestream-test popluate -db ./test.db
// error: unknown command: popluate

// after
litestream-test populate -db ./test.db

const VALID = new Set(["load", "populate", "shrink", "validate", "version"]);
const cmd = process.argv[2];
if (!VALID.has(cmd)) {
  throw new Error(`unknown command: ${cmd}. Run 'litestream-test' for usage.`);
}

function isKnownCommand(cmd) {
  return ["load", "populate", "shrink", "validate", "version"].includes(cmd);
}

try {
  await run("litestream-test", [cmd, ...args]);
} catch (e) {
  if (String(e).startsWith("unknown command")) {
    const usage = await run("litestream-test", []); // prints valid commands
    console.error(`${e.message}\n${usage.stdout}`);
  }
  throw e;
}

When it happens

Trigger: Running `litestream-test <something>` where <something> is misspelled, not installed in this build's command table, or omitted entirely (fs.Arg(0) is empty string).

Common situations: Typos like `litestream-test popluate`; assuming a subcommand exists when it was added in a newer version; running the bare binary with no subcommand at all.

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
• config file not found
• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• database path required

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