benbjohnson/litestream · error

'meta-dir' can only be used with a directory

Error message

'meta-dir' can only be used with a directory

What it means

NewDBFromConfig instantiates a DB from a DBConfig and refuses configs where MetaDir is set. meta-dir is only meaningful for directory replication, which is handled by NewDBsFromDirectoryConfig, so a per-database config carrying meta-dir is invalid here and produces this error instead of a DB.

Source

Thrown at cmd/litestream/main.go:747

	MetaPath           *string        `yaml:"meta-path"`
	MetaDir            *string        `yaml:"meta-dir"`
	MonitorInterval    *time.Duration `yaml:"monitor-interval"`
	CheckpointInterval *time.Duration `yaml:"checkpoint-interval"`
	BusyTimeout        *time.Duration `yaml:"busy-timeout"`
	MinCheckpointPageN *int           `yaml:"min-checkpoint-page-count"`
	TruncatePageN      *int           `yaml:"truncate-page-n"`
	MaxSyncWALBytes    *int64         `yaml:"max-sync-wal-bytes"`

	RestoreIfDBNotExists bool `yaml:"restore-if-db-not-exists"`

	Replica  *ReplicaConfig   `yaml:"replica"`
	Replicas []*ReplicaConfig `yaml:"replicas"` // Deprecated
}

// NewDBFromConfig instantiates a DB based on a configuration.
func NewDBFromConfig(dbc *DBConfig) (*litestream.DB, error) {
	if dbc.MetaDir != nil {
		return nil, fmt.Errorf("'meta-dir' can only be used with a directory")
	}

	configPath, err := expand(dbc.Path)
	if err != nil {
		return nil, err
	}

	// Initialize database with given path.
	db := litestream.NewDB(configPath)

	// Override default database settings if specified in configuration.
	if dbc.MetaPath != nil {
		expandedMetaPath, err := expand(*dbc.MetaPath)
		if err != nil {
			return nil, fmt.Errorf("failed to expand meta path: %w", err)
		}
		dbc.MetaPath = &expandedMetaPath
		db.SetMetaPath(expandedMetaPath)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Remove `meta-dir:` from the database entry, or switch the entry to `dir:` + `pattern:` replication so directory config handling is used.
2. Use `meta-path:` instead if you want a custom metadata location for a single database.
3. Consult `litestream version`/docs to confirm the supported config keys for your release.

Example fix

# before
databases:
  - path: /var/db/app.db
    meta-dir: /var/lib/meta
# after
databases:
  - path: /var/db/app.db
    meta-path: /var/lib/meta/app

if dbc.MetaDir != nil {
    return fmt.Errorf("meta-dir invalid for single-database config")
}

When it happens

Trigger: Any code path constructing DBs one at a time (Run, newDBFromDirectoryEntry, loadFromConfig) with a DBConfig whose MetaDir field is non-nil — i.e. the YAML entry has `meta-dir:` but is processed as a single (path-based) database.

Common situations: User places meta-dir on a path-based database entry after a version upgrade where the option semantics changed; template configs mixing directory and single-DB options.

Related errors

• database config #%d: 'watch' can only be enabled with a dire
• database config #%d: 'meta-dir' can only be used with a dire
• database config #%d: cannot specify both 'meta-path' and 'me
• directory path is required for directory replication
• pattern is required for directory replication

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