{"record":{"id":"db30d6d609b6d257","repo":"benbjohnson/litestream","slug":"cannot-specify-force-snapshot-flag-without-once","errorCode":null,"errorMessage":"cannot specify -force-snapshot flag without -once","messagePattern":"cannot specify -force-snapshot flag without -once","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/replicate.go","lineNumber":168,"sourceCode":"\t// Apply restore-if-db-not-exists flag to all databases if specified.\n\t// This allows the CLI flag to work with config files.\n\tif *restoreIfDBNotExists {\n\t\tfor _, dbConfig := range c.Config.DBs {\n\t\t\tdbConfig.RestoreIfDBNotExists = true\n\t\t}\n\t}\n\n\t// Set one-shot replication flags and validate their usage.\n\tc.once = *onceFlag\n\tc.forceSnapshot = *forceSnapshotFlag\n\tc.enforceRetention = *enforceRetentionFlag\n\n\t// Validate flag combinations.\n\tif c.once && c.Config.Exec != \"\" {\n\t\treturn fmt.Errorf(\"cannot specify -once flag with -exec\")\n\t}\n\tif c.forceSnapshot && !c.once {\n\t\treturn fmt.Errorf(\"cannot specify -force-snapshot flag without -once\")\n\t}\n\tif c.enforceRetention && !c.once {\n\t\treturn fmt.Errorf(\"cannot specify -enforce-retention flag without -once\")\n\t}\n\n\treturn nil\n}\n\n// Run loads all databases specified in the configuration.\nfunc (c *ReplicateCommand) Run(ctx context.Context) (err error) {\n\t// Display version information.\n\tslog.Info(\"litestream\", \"version\", Version, \"level\", c.Config.Logging.Level)\n\n\t// Start MCP server if enabled\n\tif c.Config.MCPAddr != \"\" {\n\t\tc.MCP, err = NewMCP(ctx, c.Config.ConfigPath)\n\t\tif err != nil {\n\t\t\treturn err","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/replicate.go#L150-L186","documentation":"`-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.","triggerScenarios":"Running `litestream replicate -force-snapshot db.sqlite url` without `-once` — c.forceSnapshot is true while c.once is false.","commonSituations":"Users wanting to force a fresh snapshot to a new replica URL forgetting that the flag only works with one-shot mode.","solutions":["Add `-once` so the snapshot is forced during the single replication pass","Remove `-force-snapshot` if continuous replication is desired (snapshots happen on schedule anyway)","Delete the replica's stored LTX state (or use `litestream reset`) if the goal is re-snapshotting an existing replica"],"exampleFix":"// before\nlitestream replicate -force-snapshot db.sqlite s3://bucket/db\n// after\nlitestream replicate -once -force-snapshot db.sqlite s3://bucket/db","handlingStrategy":"validation","validationCode":"if [ -n \"$(printf '%s' \"$ARGS\" | grep -- '-force-snapshot')\" ] && ! printf '%s' \"$ARGS\" | grep -q -- '-once'; then\n  echo \"-force-snapshot requires -once\" >&2; exit 1\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat -force-snapshot, -enforce-retention as -once-only modifiers","Document flag prerequisites in deployment scripts","Use the config file for continuous-mode behavior instead of one-shot flags"],"tags":["cli","flags","validation"],"backgroundTag":"invalid-flag-value","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}