{"record":{"id":"1e32c96557f9c7e6","repo":"hashicorp/nomad","slug":"failed-to-create-state-database-v","errorCode":null,"errorMessage":"failed to create state database: %v","messagePattern":"failed to create state database: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"client/state/db_bolt.go","lineNumber":204,"sourceCode":"func NewBoltStateDB(logger hclog.Logger, stateDir string) (StateDB, error) {\n\tfn := filepath.Join(stateDir, \"state.db\")\n\n\t// Check to see if the DB already exists\n\tfi, err := os.Stat(fn)\n\tif err != nil && !os.IsNotExist(err) {\n\t\treturn nil, err\n\t}\n\tfirstRun := fi == nil\n\n\t// Timeout to force failure when accessing a data dir that is already in use\n\ttimeout := &bbolt.Options{Timeout: 5 * time.Second}\n\n\t// Create or open the boltdb state database\n\tdb, err := boltdd.Open(fn, 0600, timeout)\n\tif err == bbolt.ErrTimeout {\n\t\treturn nil, fmt.Errorf(\"timed out while opening database, is another Nomad process accessing data_dir %s?\", stateDir)\n\t} else if err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create state database: %v\", err)\n\t}\n\n\tsdb := &BoltStateDB{\n\t\tstateDir: stateDir,\n\t\tdb:       db,\n\t\tlogger:   logger,\n\t}\n\n\t// If db did not already exist, initialize metadata fields\n\tif firstRun {\n\t\tif err := sdb.init(); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\n\treturn sdb, nil\n}\n","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/state/db_bolt.go#L186-L222","documentation":"NewBoltStateDB wraps any error from boltdd.Open (other than the lock timeout) with \"failed to create state database\". This covers permission problems, path issues, corruption, or any other failure to create/open the client's bolt state database file under the state directory.","triggerScenarios":"boltdd.Open(fn, 0600, timeout) returns a non-timeout error during client startup: the state db file path is unwritable (permissions/ownership), the parent state dir is missing or is not a directory, the db file is corrupt, or the filesystem is full/read-only.","commonSituations":"data_dir owned by a different user than the Nomad agent runs as; read-only container filesystem or full disk; corrupted bolt file after crash/power loss; SELinux/AppArmor denying write access to the data dir.","solutions":["Read the wrapped %v cause for the underlying OS/db error","Fix permissions on data_dir and the state db file so the Nomad agent user can write (chown/chmod)","Check disk space and that the filesystem is writable","If the bolt file is corrupt, restore from backup or move the corrupt state aside (losing local client state)"],"exampleFix":"# before\nls -l /var/nomad/client  # owned by root, agent runs as nomad\n# after\nchown -R nomad:nomad /var/nomad\nsystemctl restart nomad","handlingStrategy":"try-catch","validationCode":"if err := canWriteDir(filepath.Join(stateDir, \"client\")); err != nil {\n    return fmt.Errorf(\"data_dir not writable by nomad user: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"sdb, err := NewBoltStateDB(stateDir, logger)\nif err != nil && strings.HasPrefix(err.Error(), \"failed to create state database\") {\n    logger.Error(\"cannot open bolt state db; check permissions/disk/corruption\", \"dir\", stateDir, \"cause\", err)\n    return err\n}","preventionTips":["Ensure data_dir is owned by and writable by the user Nomad runs as","Monitor disk free space and mount state on a writable, persistent volume","Back up the state db so corrupt files can be restored instead of discarded","Check LSM (SELinux/AppArmor) policies allow Nomad writes to data_dir"],"tags":["nomad","boltdb","state-database","filesystem"],"backgroundTag":"database-open-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}