{"record":{"id":"30ae144d9511efcf","repo":"nats-io/nats-server","slug":"could-not-create-storage-directory-v","errorCode":null,"errorMessage":"could not create storage directory - %v","messagePattern":"could not create storage directory - (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/filestore.go","lineNumber":440,"sourceCode":"\t}\n\tif fcfg.BlockSize > maxBlockSize {\n\t\treturn nil, fmt.Errorf(\"filestore max block size is %s\", friendlyBytes(maxBlockSize))\n\t}\n\tif fcfg.CacheExpire == 0 {\n\t\tfcfg.CacheExpire = defaultCacheBufferExpiration\n\t}\n\tif fcfg.SubjectStateExpire == 0 {\n\t\tfcfg.SubjectStateExpire = defaultFssExpiration\n\t}\n\tif fcfg.SyncInterval == 0 {\n\t\tfcfg.SyncInterval = defaultSyncInterval\n\t}\n\tdios := fcfg.srv.diskIOSemaphore()\n\n\t// Check the directory\n\tif stat, err := os.Stat(fcfg.StoreDir); os.IsNotExist(err) {\n\t\tif err := os.MkdirAll(fcfg.StoreDir, defaultDirPerms); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"could not create storage directory - %v\", err)\n\t\t}\n\t} else if stat == nil || !stat.IsDir() {\n\t\treturn nil, fmt.Errorf(\"storage directory is not a directory\")\n\t}\n\ttmpfile, err := os.CreateTemp(fcfg.StoreDir, \"_test_\")\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"storage directory is not writable\")\n\t}\n\n\ttmpfile.Close()\n\tdios.acquire()\n\tos.Remove(tmpfile.Name())\n\tdios.release()\n\n\tfs = &fileStore{\n\t\tfcfg:       fcfg,\n\t\tdios:       dios,\n\t\tpsim:       stree.NewSubjectTree[psi](),","sourceCodeStart":422,"sourceCodeEnd":458,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/filestore.go#L422-L458","documentation":"During file store setup, os.Stat shows the configured StoreDir does not exist, and the subsequent os.MkdirAll attempt failed (permissions, read-only filesystem, path conflicts). The underlying OS error is wrapped into this message. It indicates the server cannot provision its JetStream storage directory.","triggerScenarios":"os.Stat(StoreDir) returns fs.ErrNotExist and os.MkdirAll(StoreDir, defaultDirPerms) returns an error (server/filestore.go:440), e.g. parent directory not writable or StoreDir path invalid.","commonSituations":"JetBeam/StoreDir pointing to a path the server user cannot create (bad ownership, root-only parent); containers with read-only volumes; StoreDir containing a file component where a directory is needed elsewhere.","solutions":["Create the storage directory manually and grant the server user write permission (mkdir -p <dir>; chown)","Fix StoreDir in the JetStream config to an existing writable path","Check the wrapped %v OS error for the root cause (EACCES, EROFS, ENOTDIR)","Verify the mount is writable if running in a container"],"exampleFix":"// before (server config)\nstore_dir: \"/jetstream/data\"\n// after (ensure it exists and is writable first)\n// $ sudo mkdir -p /jetstream/data && sudo chown nats:nats /jetstream/data\nstore_dir: \"/jetstream/data\"","handlingStrategy":"validation","validationCode":"d := filepath.Join(storeDir, \"..\")\nif fi, err := os.Stat(d); err != nil || !fi.IsDir() {\n    return fmt.Errorf(\"parent of %s missing or not a directory\", storeDir)\n}\nif err := os.MkdirAll(storeDir, 0o755); err != nil {\n    return fmt.Errorf(\"pre-create store dir failed: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if _, err := os.Stat(storeDir); err != nil {\n    return fmt.Errorf(\"storage dir unusable: %w\", err)\n}","preventionTips":["Pre-create store_dir in provisioning with correct ownership","Run the server as a user with write access to the data volume","Ensure container volumes are mounted read-write"],"tags":["jetstream","filesystem","permissions","go"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}