benbjohnson/litestream · info

database already exists, skipping

Error message

database already exists, skipping

What it means

errSkipDBExists is a sentinel returned by restore's loadFromURL/loadFromConfig when the target database file already exists and -if-db-not-exists was set. Run treats it as success: it logs "database already exists, skipping" and returns nil rather than overwriting an existing database.

Source

Thrown at cmd/litestream/restore.go:453

	# Restore latest replica for database to new /tmp directory
	$ litestream restore -o /tmp/db /path/to/db

	# Restore database from S3 replica URL.
	$ litestream restore -o /tmp/db s3://mybucket/db

	# Preview restore plan without writing a database.
	$ litestream restore -dry-run -o /tmp/db s3://mybucket/db

	# Continuously restore (follow) a database from a replica.
	$ litestream restore -f -o /tmp/read-replica.db s3://mybucket/db

`[1:],
		DefaultConfigPath(),
	)
}

var errSkipDBExists = errors.New("database already exists, skipping")

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. No action needed if skipping is intended — this is a success path
2. Delete or move the existing database file if you truly want a fresh restore
3. Omit -if-db-not-exists if you want the default overwrite/conflict behavior instead
4. Check logs for "database already exists, skipping" to confirm idempotent skip

Example fix

// before
litestream restore -o /data/app.db rep  // fails if db exists
// after (idempotent)
litestream restore -if-db-not-exists -o /data/app.db rep  // exits 0 if db exists

if _, err := os.Stat(dbPath); err == nil {
    slog.Info("db exists; restore will be skipped with -if-db-not-exists")
}

When it happens

Trigger: Running `litestream restore -if-db-not-exists` (or the library equivalent) when the output database path already exists on disk; the flag converts what would be a destructive conflict into a graceful skip.

Common situations: Idempotent startup scripts / systemd units that restore before launching an app, containers re-running restore against a mounted volume that already holds the database.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• no snapshots available
• too many arguments
• invalid -integrity-check value: %s
• cannot specify a replica URL and the -config flag

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