What causes "failed to expand meta path: %w" in benbjohnson/litestream?

Ensure every env variable referenced in meta-path is defined in the runtime environment.

failed to expand meta path: %w

Error message

failed to expand meta path: %w

What it means

NewDBFromConfig expands environment variables in dbc.MetaPath via expand(); if expansion fails (e.g. a referenced env variable is unset in strict setups), it wraps the error with "failed to expand meta path: %w" and aborts DB creation.

Source

Thrown at cmd/litestream/main.go:762

// 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)
	}
	if dbc.MonitorInterval != nil {
		db.MonitorInterval = *dbc.MonitorInterval
	}
	if dbc.CheckpointInterval != nil {
		db.CheckpointInterval = *dbc.CheckpointInterval
	}
	if dbc.BusyTimeout != nil {
		db.BusyTimeout = *dbc.BusyTimeout
	}
	if dbc.MinCheckpointPageN != nil {
		db.MinCheckpointPageN = *dbc.MinCheckpointPageN
	}
	if dbc.TruncatePageN != nil {
		db.TruncatePageN = *dbc.TruncatePageN

View on GitHub (pinned to 4ed7a308f6)

Solutions

Ensure every env variable referenced in meta-path is defined in the runtime environment.
Simplify meta-path to a literal path to avoid expansion entirely.
Check the wrapped inner error (%w) for the exact expansion failure and fix accordingly.

Example fix

# before
meta-path: ${LITESTREAM_META_DIR}/app
# after (env guaranteed via systemd)
# systemd unit:
Environment=LITESTREAM_META_DIR=/var/lib/litestream-meta
# config
meta-path: ${LITESTREAM_META_DIR}/app

Defensive patterns

Strategy: validation

Validate before calling

for _, v := range envRefs(metaPath) {
    if os.Getenv(v) == "" {
        return fmt.Errorf("env var %s used in meta-path is unset", v)
    }
}

Try / catch

db, err := litestream.NewDBFromConfig(dbc)
if err != nil {
    if strings.Contains(err.Error(), "failed to expand meta path") {
        log.Fatalf("check env vars in meta-path: %v", err)
    }
}

Prevention

Define all referenced env vars in systemd/launcher environments
Prefer literal paths over $VAR in meta-path
Test expansion with the exact service environment

When it happens

Trigger: A database entry with `meta-path:` containing variables (e.g. ${HOME} or $PID-style placeholders) whose expansion function returns an error, hit when Run/newDBFromDirectoryEntry/loadFromConfig calls NewDBFromConfig.

Common situations: Config uses $VAR syntax relying on environment variables that are not set in the service environment (systemd unit without Environment=); quoting issues in YAML around $.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

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