{"record":{"id":"f35dc0f40899072b","repo":"benbjohnson/litestream","slug":"meta-dir-can-only-be-used-with-a-directory","errorCode":null,"errorMessage":"'meta-dir' can only be used with a directory","messagePattern":"'meta-dir' can only be used with a directory","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":747,"sourceCode":"\tMetaPath           *string        `yaml:\"meta-path\"`\n\tMetaDir            *string        `yaml:\"meta-dir\"`\n\tMonitorInterval    *time.Duration `yaml:\"monitor-interval\"`\n\tCheckpointInterval *time.Duration `yaml:\"checkpoint-interval\"`\n\tBusyTimeout        *time.Duration `yaml:\"busy-timeout\"`\n\tMinCheckpointPageN *int           `yaml:\"min-checkpoint-page-count\"`\n\tTruncatePageN      *int           `yaml:\"truncate-page-n\"`\n\tMaxSyncWALBytes    *int64         `yaml:\"max-sync-wal-bytes\"`\n\n\tRestoreIfDBNotExists bool `yaml:\"restore-if-db-not-exists\"`\n\n\tReplica  *ReplicaConfig   `yaml:\"replica\"`\n\tReplicas []*ReplicaConfig `yaml:\"replicas\"` // Deprecated\n}\n\n// NewDBFromConfig instantiates a DB based on a configuration.\nfunc NewDBFromConfig(dbc *DBConfig) (*litestream.DB, error) {\n\tif dbc.MetaDir != nil {\n\t\treturn nil, fmt.Errorf(\"'meta-dir' can only be used with a directory\")\n\t}\n\n\tconfigPath, err := expand(dbc.Path)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// Initialize database with given path.\n\tdb := litestream.NewDB(configPath)\n\n\t// Override default database settings if specified in configuration.\n\tif dbc.MetaPath != nil {\n\t\texpandedMetaPath, err := expand(*dbc.MetaPath)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to expand meta path: %w\", err)\n\t\t}\n\t\tdbc.MetaPath = &expandedMetaPath\n\t\tdb.SetMetaPath(expandedMetaPath)","sourceCodeStart":729,"sourceCodeEnd":765,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L729-L765","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove `meta-dir:` from the database entry, or switch the entry to `dir:` + `pattern:` replication so directory config handling is used.","Use `meta-path:` instead if you want a custom metadata location for a single database.","Consult `litestream version`/docs to confirm the supported config keys for your release."],"exampleFix":"# before\ndatabases:\n  - path: /var/db/app.db\n    meta-dir: /var/lib/meta\n# after\ndatabases:\n  - path: /var/db/app.db\n    meta-path: /var/lib/meta/app","handlingStrategy":"validation","validationCode":"if dbc.MetaDir != nil {\n    return fmt.Errorf(\"meta-dir invalid for single-database config\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remove meta-dir from path-based entries after upgrades","Review release notes when upgrading Litestream","Validate config keys against current docs"],"tags":["config","validation","litestream"],"backgroundTag":"unsupported-config-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"}