{"record":{"id":"ae2d81049ad82070","repo":"mastra-ai/mastra","slug":"compositefilesystem-requires-at-least-one-mount","errorCode":null,"errorMessage":"CompositeFilesystem requires at least one mount","messagePattern":"CompositeFilesystem requires at least one mount","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/filesystem/composite-filesystem.ts","lineNumber":101,"sourceCode":"  readonly name = 'CompositeFilesystem';\n  readonly provider = 'composite';\n\n  readonly readOnly?: boolean;\n  status: ProviderStatus = 'ready';\n\n  private readonly _mounts: Map<string, WorkspaceFilesystem>;\n\n  constructor(config: CompositeFilesystemConfig<TMounts>) {\n    this.id = `cfs-${Date.now().toString(36)}`;\n    this._mounts = new Map();\n\n    for (const [path, fs] of Object.entries(config.mounts)) {\n      const normalized = this.normalizePath(path);\n      this._mounts.set(normalized, fs);\n    }\n\n    if (this._mounts.size === 0) {\n      throw new Error('CompositeFilesystem requires at least one mount');\n    }\n\n    // Composite is read-only when every mount is read-only\n    this.readOnly = [...this._mounts.values()].every(fs => fs.readOnly) || undefined;\n\n    // Validate no nested mount paths (e.g., /data and /data/sub)\n    const mountPaths = [...this._mounts.keys()];\n    for (const a of mountPaths) {\n      for (const b of mountPaths) {\n        if (a !== b && b.startsWith(a + '/')) {\n          throw new Error(`Nested mount paths are not supported: \"${b}\" is nested under \"${a}\"`);\n        }\n      }\n    }\n  }\n\n  /**\n   * Get all mount paths.","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/filesystem/composite-filesystem.ts#L83-L119","documentation":"CompositeFilesystem aggregates multiple mounted filesystems under path prefixes; it requires config.mounts to contain at least one entry. With zero mounts, no path could ever resolve, so the constructor fails fast instead of producing a filesystem where every operation errors. It is raised in the constructor, so the object is never created.","triggerScenarios":"Constructing new CompositeFilesystem({ mounts: {} }) or with a mounts object that is empty, or where all entries are filtered out before mounting (empty normalized keys).","commonSituations":"Building mounts from an environment variable or config file that parsed to an empty object; conditional mounting logic that skipped all backends; typo in the config key holding mount definitions.","solutions":["Pass at least one mount, e.g. { mounts: { '/': new LocalFilesystem('/data') } }.","Log/inspect the mounts object passed to the constructor; fix the config source that produced an empty map.","If mounts are dynamic, guard construction: only create the composite after confirming at least one backend is available."],"exampleFix":"// before\nnew CompositeFilesystem({ mounts: {} });\n// after\nconst mounts = loadMountsFromConfig();\nif (Object.keys(mounts).length === 0) throw new Error('No workspace mounts configured');\nnew CompositeFilesystem({ mounts });","handlingStrategy":"validation","validationCode":"if (!mounts || Object.keys(mounts).length === 0) {\n  throw new Error('CompositeFilesystem config.mounts must contain at least one entry');\n}\nconst composite = new CompositeFilesystem({ mounts });","typeGuard":"function hasMounts(cfg: unknown): cfg is { mounts: Record<string, WorkspaceFilesystem> } {\n  return typeof cfg === 'object' && cfg !== null && 'mounts' in cfg &&\n    typeof (cfg as any).mounts === 'object' && Object.keys((cfg as any).mounts).length > 0;\n}","tryCatchPattern":"let fs: CompositeFilesystem;\ntry { fs = new CompositeFilesystem({ mounts }); } catch (e) { if ((e as Error).message.includes('at least one mount')) { fs = new CompositeFilesystem({ mounts: { '/': fallbackFs } }); } else throw e; }","preventionTips":["Validate mount config at startup, before constructing the composite.","Log parsed mounts when loading from env/config files.","Keep a default fallback mount for '/' in environments that may have none."],"tags":["workspace","filesystem","configuration","constructor"],"backgroundTag":"empty-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}