benbjohnson/litestream · error

cannot specify -enforce-retention flag without -once

Error message

cannot specify -enforce-retention flag without -once

What it means

`-enforce-retention` forces retention enforcement at the end of a run and is only meaningful for a `-once` single-pass run; in continuous mode retention runs on its schedule. ParseFlags rejects the combination so the flag is never silently ignored.

Source

Thrown at cmd/litestream/replicate.go:171

		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
		}
		go c.MCP.Start(c.Config.MCPAddr)
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Add `-once` to the command line so retention is enforced after the single pass
2. Remove `-enforce-retention` and rely on the continuous retention schedule
3. If cleanup without replication is needed, use the `-once` mode dedicated to it

Example fix

// before
litestream replicate -enforce-retention db.sqlite s3://bucket/db
// after
litestream replicate -once -enforce-retention db.sqlite s3://bucket/db

if printf '%s' "$ARGS" | grep -q -- '-enforce-retention' && ! printf '%s' "$ARGS" | grep -q -- '-once'; then
  echo "-enforce-retention requires -once" >&2; exit 1
fi

When it happens

Trigger: Running `litestream replicate -enforce-retention db.sqlite url` without `-once` — c.enforceRetention is true while c.once is false.

Common situations: Ops scripts cleaning up old LTX files before/after a one-shot backup that forget the required `-once` flag.

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 -force-snapshot 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/2e67d345e8a2450f. Report an issue: GitHub.