{"record":{"id":"eb3e3d817cd0b330","repo":"mastra-ai/mastra","slug":"configured-domain-path-directory-is-a-file-e","errorCode":null,"errorMessage":"Configured domain path \"${directory}\" is a file, expected a directory","messagePattern":"Configured domain path \"(.+?)\" is a file, expected a directory","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/filesystem-db.ts","lineNumber":111,"sourceCode":"    renameSync(tmpPath, filePath);\n  }\n\n  /**\n   * Clear all data from a domain JSON file.\n   */\n  clearDomain(filename: string): void {\n    this.writeDomain(filename, {});\n  }\n\n  listDomainFiles(directory: string, extension = '.json'): string[] {\n    const baseDir = resolve(this.dir, directory);\n    const rootDir = resolve(this.dir);\n    if (!baseDir.startsWith(rootDir + sep) && baseDir !== rootDir) {\n      throw new Error(`Path traversal detected: directory \"${directory}\" escapes storage directory`);\n    }\n    if (!existsSync(baseDir)) return [];\n    if (!statSync(baseDir).isDirectory()) {\n      throw new Error(`Configured domain path \"${directory}\" is a file, expected a directory`);\n    }\n\n    return readdirSync(baseDir)\n      .filter(file => extname(file) === extension && statSync(join(baseDir, file)).isFile())\n      .map(file => `${directory}/${file}`);\n  }\n\n  /**\n   * Check whether a domain file currently exists on disk.\n   */\n  domainFileExists(filename: string): boolean {\n    const filePath = resolve(this.dir, filename);\n    const rootDir = resolve(this.dir);\n    if (!filePath.startsWith(rootDir + sep) && filePath !== rootDir) {\n      throw new Error(`Path traversal detected: file \"${filename}\" escapes storage directory`);\n    }\n    return existsSync(filePath);\n  }","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/filesystem-db.ts#L93-L129","documentation":"After passing the traversal check, listDomainFiles() stats the resolved directory and throws if it exists but is a regular file instead of a directory. The storage expects each domain path to be a directory of JSON files.","triggerScenarios":"The configured domain path (e.g. `directory` argument or a storage dir layout) points at an existing file, so `readdirSync` would fail; listDomainFiles is called on a path where a file was placed where a directory is expected.","commonSituations":"A file (e.g. an accidental archive, editor artifact, or JSON written to the directory path) collides with a domain directory name; migrating storage layouts where old data was a single file; wrong `directory` argument naming a file.","solutions":["Remove or rename the file at that path so the domain path can be a directory, or move its contents into a directory of that name.","Fix the `directory` argument to point at an actual directory within storage.","Inspect the storage root (`this.dir`) to see what occupies the path: `ls -la <root>/<directory>`.","If migrating layouts, move legacy single-file data into the per-domain directory structure."],"exampleFix":"// before\nfs.writeFileSync(path.join(dir, 'workflows'), data); // file where dir expected\n\n// after\nfs.mkdirSync(path.join(dir, 'workflows'), { recursive: true });\nfs.writeFileSync(path.join(dir, 'workflows', 'entry.json'), data);","handlingStrategy":"validation","validationCode":"const fs = require('fs');\nfunction ensureDomainDir(base, dir) {\n  const p = require('path').join(base, dir);\n  if (fs.existsSync(p) && !fs.statSync(p).isDirectory()) {\n    throw new Error(`${p} is a file; expected a directory`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return db.listDomainFiles(dir);\n} catch (e) {\n  if (e.message.includes('is a file, expected a directory')) {\n    // surface a clear config/migration error to the operator\n    throw new Error(`Storage layout invalid at \"${dir}\": move or remove the file.`);\n  }\n  throw e;\n}","preventionTips":["Check storage root layout after version/migration upgrades.","Never write files to paths that double as domain directories.","Add a startup check that each expected domain path is a directory.","Keep editor/backup artifacts (e.g. workflows.json~, archive files) out of the storage root."],"tags":["filesystem","storage","configuration"],"backgroundTag":"path-is-not-a-directory","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}