benbjohnson/litestream · error

db path required

Error message

db path required

What it means

Store.UnregisterDB requires a non-empty database path and returns this error for the empty string. Without a path there is nothing to look up in the store's registry. It is a caller misuse guard, raised before any locking or lookup occurs.

Source

Thrown at store.go:348

				db.Logger.Error("close duplicate db", "path", db.Path(), "error", err)
			}
			return nil
		}
	}

	s.dbs = append(s.dbs, db)
	s.mu.Unlock()

	// Start heartbeat monitor if heartbeat is configured and monitor isn't running.
	s.startHeartbeatMonitorIfNeeded()

	return nil
}

// UnregisterDB stops monitoring the database at the provided path and closes it.
func (s *Store) UnregisterDB(ctx context.Context, path string) error {
	if path == "" {
		return fmt.Errorf("db path required")
	}

	s.mu.Lock()

	idx := -1
	var db *DB
	for i, existing := range s.dbs {
		if existing.Path() == path {
			idx = i
			db = existing
			break
		}
	}

	if db == nil {
		s.mu.Unlock()
		return nil
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Pass the actual absolute path of the registered database to UnregisterDB
2. Validate/trim the path at config load and reject empty values early
3. If the path is unknown, list registered DBs (s.DBs()) to find the correct path

Example fix

// before
path := cfg.DBPath // ""
store.UnregisterDB(ctx, path)

// after
if cfg.DBPath == "" {
    return fmt.Errorf("config: db path must not be empty")
}
return store.UnregisterDB(ctx, cfg.DBPath)

if path == "" {
    return fmt.Errorf("db path must be a non-empty absolute path")
}

if err := store.UnregisterDB(ctx, path); err != nil && err.Error() == "db path required" {
    // caller passed empty path; fix input source, no retry
}

When it happens

Trigger: Calling UnregisterDB(ctx, "") — commonly from a handler (handleUnregister) or path-removal helpers (removeDatabase, removeDatabasesUnder) that received an empty path from config parsing or an unset variable.

Common situations: Config file with an empty db path entry; a variable holding the db path never populated; CLI/API callers passing an empty string after trimming an invalid input.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• db required
• store required
• snapshot interval must be greater than 0
• snapshot retention must be greater than 0
• compaction interval must be greater than 0

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