{"record":{"id":"a932b3eff80c161e","repo":"mastra-ai/mastra","slug":"this-name-per-entity-files-directory-is-not-co","errorCode":null,"errorMessage":"${this.name}: per-entity files directory is not configured","messagePattern":"(.+?): per-entity files directory is not configured","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/filesystem-versioned.ts","lineNumber":162,"sourceCode":"   * after the git history.\n   */\n  private gitVersionCounts = new Map<string, number>();\n\n  constructor(config: FilesystemVersionedConfig) {\n    this.db = config.db;\n    this.entitiesFile = config.entitiesFile;\n    this.parentIdField = config.parentIdField;\n    this.name = config.name;\n    this.versionMetadataFields = config.versionMetadataFields;\n    this.gitHistoryLimit = config.gitHistoryLimit ?? 50;\n    this.perEntityFilesDir = config.perEntityFilesDir;\n    this.shouldPersistToPerEntityFile = config.shouldPersistToPerEntityFile;\n    this.perEntitySnapshotFilter = config.perEntitySnapshotFilter;\n  }\n\n  private perEntityFilename(entityId: string): string {\n    if (!this.perEntityFilesDir) {\n      throw new Error(`${this.name}: per-entity files directory is not configured`);\n    }\n    return getSourceControlEntityFilePath(this.perEntityFilesDir, entityId);\n  }\n\n  private entityIdFromPerEntityFilename(filename: string): string {\n    const basename = filename.split('/').pop() ?? filename;\n    return decodeURIComponent(basename.replace(/\\.json$/, ''));\n  }\n\n  /**\n   * Check if a version ID represents a git-based version.\n   */\n  static isGitVersion(id: string): boolean {\n    return id.startsWith(GIT_VERSION_PREFIX);\n  }\n\n  /**\n   * Hydrate in-memory state from the on-disk JSON file.","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/filesystem-versioned.ts#L144-L180","documentation":"A versioned filesystem domain computes per-entity snapshot file paths from a dedicated perEntityFilesDir; when that configuration field is unset, perEntityFilename() throws instead of writing files to an undefined location. It is a configuration guard, not a runtime failure of data operations.","triggerScenarios":"Calling filename() or persistToDisk() on a versioned domain constructed without `perEntityFilesDir` in its config, while per-entity persistence (shouldPersistToPerEntityFile) is enabled/used.","commonSituations":"Custom storage subclass forgetting to set perEntityFilesDir in its config; enabling shouldPersistToPerEntityFile without supplying the directory; partial migration of config schemas between versions.","solutions":["Set `perEntityFilesDir` in the domain's config to a directory under the storage root.","Only enable `shouldPersistToPerEntityFile: true` when perEntityFilesDir is provided.","If per-entity files are not wanted, avoid the code path that calls filename()/persistToDisk per entity.","Check the storage subclass's config wiring to ensure it passes the field through (see constructor assignment of this.perEntityFilesDir)."],"exampleFix":"// before\nnew MyVersionedDomain({ dir, shouldPersistToPerEntityFile: true }); // throws on persist\n\n// after\nnew MyVersionedDomain({\n  dir,\n  shouldPersistToPerEntityFile: true,\n  perEntityFilesDir: path.join(dir, 'entities'),\n});","handlingStrategy":"validation","validationCode":"function assertPerEntityConfig(config) {\n  if (config.shouldPersistToPerEntityFile && !config.perEntityFilesDir) {\n    throw new Error('perEntityFilesDir is required when shouldPersistToPerEntityFile is true');\n  }\n  return config;\n}","typeGuard":"function hasPerEntityDir(cfg) {\n  return typeof cfg.perEntityFilesDir === 'string' && cfg.perEntityFilesDir.length > 0;\n}","tryCatchPattern":"try {\n  await domain.persistToDisk();\n} catch (e) {\n  if (e.message.includes('per-entity files directory is not configured')) {\n    throw new Error(`${domain.name}: set perEntityFilesDir in the domain config to enable per-entity files.`);\n  }\n  throw e;\n}","preventionTips":["Always provide perEntityFilesDir when enabling shouldPersistToPerEntityFile.","Validate domain config at construction time (fail fast).","Point perEntityFilesDir at a directory inside the storage root so traversal checks pass.","Re-check config wiring when upgrading storage subclasses across versions."],"tags":["storage","configuration","filesystem"],"backgroundTag":"missing-config-option","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}