What causes "cannot specify -once flag with -exec" in benbjohnson/litestream?

Drop the `-once` flag if you need the exec subprocess supervision

cannot specify -once flag with -exec

Error message

cannot specify -once flag with -exec

What it means

The `-once` flag runs a single replication pass and exits, while `-exec` keeps Litestream alive as a supervisor wrapping a subprocess. These lifecycles are incompatible: `-once` would exit after one sync while the exec'd process may still be running. ParseFlags rejects the combination up front.

Source

Thrown at cmd/litestream/replicate.go:165

		c.Config.Exec = *execFlag
	}

	// 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 != "" {

View on GitHub (pinned to 4ed7a308f6)

Solutions

Drop the `-once` flag if you need the exec subprocess supervision
Drop the `-exec` argument if you only want a single replication pass
Run two separate litestream invocations: one `-once` replicate and one that runs your command

Example fix

// before
litestream replicate -once -exec "./backup-hook.sh" db.sqlite s3://bucket/db
// after
litestream replicate -exec "./backup-hook.sh" db.sqlite s3://bucket/db
# or
litestream replicate -once db.sqlite s3://bucket/db

Defensive patterns

Strategy: validation

Validate before calling

# reject incompatible flag combos before exec
set -e
for a in "$@"; do
  if [ "$a" = "-once" ] && printf '%s' "$CMDLINE" | grep -q -- '-exec'; then
    echo "-once cannot be combined with -exec" >&2; exit 1
  fi
done

Prevention

Remember: -once means exit-after-one-sync; -exec means long-running supervisor — never both
Keep one-shot backup scripts and exec-supervised services as separate invocations
Lint wrapper scripts for known flag combinations

When it happens

Trigger: Invoking `litestream replicate -once -exec "some-command" ...` — both c.once set and Config.Exec non-empty after flag parsing.

Common situations: One-shot backup scripts that also want to run a quick command alongside; users combining a container entrypoint pattern with a one-shot restore/replicate.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

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