benbjohnson/litestream · error

cannot specify -force-snapshot flag without -once

Error message

cannot specify -force-snapshot flag without -once

What it means

`-force-snapshot` forces a full snapshot upload on the next sync, which only makes sense in a `-once` (single-pass) run; in continuous mode the flag has no defined trigger point. ParseFlags rejects it to prevent silently ignored flags.

Source

Thrown at cmd/litestream/replicate.go:168

	// Apply restore-if-db-not-exists flag to all databases if specified.
	// This allows the CLI flag to work with config files.
	if *restoreIfDBNotExists {
		for _, dbConfig := range c.Config.DBs {
			dbConfig.RestoreIfDBNotExists = true
		}
	}

	// Set one-shot replication flags and validate their usage.
	c.once = *onceFlag
	c.forceSnapshot = *forceSnapshotFlag
	c.enforceRetention = *enforceRetentionFlag

	// Validate flag combinations.
	if c.once && c.Config.Exec != "" {
		return fmt.Errorf("cannot specify -once flag with -exec")
	}
	if c.forceSnapshot && !c.once {
		return fmt.Errorf("cannot specify -force-snapshot flag without -once")
	}
	if c.enforceRetention && !c.once {
		return fmt.Errorf("cannot specify -enforce-retention flag without -once")
	}

	return nil
}

// Run loads all databases specified in the configuration.
func (c *ReplicateCommand) Run(ctx context.Context) (err error) {
	// Display version information.
	slog.Info("litestream", "version", Version, "level", c.Config.Logging.Level)

	// Start MCP server if enabled
	if c.Config.MCPAddr != "" {
		c.MCP, err = NewMCP(ctx, c.Config.ConfigPath)
		if err != nil {
			return err

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Add `-once` so the snapshot is forced during the single replication pass
2. Remove `-force-snapshot` if continuous replication is desired (snapshots happen on schedule anyway)
3. Delete the replica's stored LTX state (or use `litestream reset`) if the goal is re-snapshotting an existing replica

Example fix

// before
litestream replicate -force-snapshot db.sqlite s3://bucket/db
// after
litestream replicate -once -force-snapshot db.sqlite s3://bucket/db

if [ -n "$(printf '%s' "$ARGS" | grep -- '-force-snapshot')" ] && ! printf '%s' "$ARGS" | grep -q -- '-once'; then
  echo "-force-snapshot requires -once" >&2; exit 1
fi

When it happens

Trigger: Running `litestream replicate -force-snapshot db.sqlite url` without `-once` — c.forceSnapshot is true while c.once is false.

Common situations: Users wanting to force a fresh snapshot to a new replica URL forgetting that the flag only works with one-shot mode.

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.

Related errors

• cannot specify -once flag with -exec
• cannot specify -enforce-retention flag without -once
• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• database path required
• database path required

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