{"record":{"id":"e006746170457666","repo":"mastra-ai/mastra","slug":"source-provider-this-provider-displayname-canno-e00674","errorCode":null,"errorMessage":"Source provider ${this.provider.displayName} cannot write files","messagePattern":"Source provider (.+?) cannot write files","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/agents/source.ts","lineNumber":418,"sourceCode":"  private getCodeDefinedAgent(agentId: string): { source?: string; __getEditorConfig?: () => unknown } | undefined {\n    try {\n      const agent = this.storageMastra?.getAgentById?.(agentId) as\n        | { source?: string; __getEditorConfig?: () => unknown }\n        | undefined;\n      return agent?.source === 'code' ? agent : undefined;\n    } catch {\n      return undefined;\n    }\n  }\n\n  private async persistSnapshot(\n    agentId: string,\n    snapshot: Record<string, unknown>,\n    message?: string,\n  ): Promise<SourceWriteResult> {\n    const capabilities = await this.provider.getCapabilities();\n    if (!capabilities.canWrite) {\n      throw new Error(capabilities.reason ?? `Source provider ${this.provider.displayName} cannot write files`);\n    }\n    const agent = this.getCodeDefinedAgent(agentId);\n    const filtered = filterSourceSnapshot(snapshot, agent?.__getEditorConfig?.(), Boolean(agent));\n    return this.provider.writeFile({\n      path: getSourceAgentFilePath(agentId),\n      ref: this.activeRefs.get(agentId),\n      content: `${stableStringify(filtered)}\\n`,\n      message,\n    });\n  }\n\n  private async loadHistory(agentId: string): Promise<void> {\n    if (this.loadedHistory.has(agentId)) return;\n\n    const capabilities = await this.provider.getCapabilities();\n    if (!capabilities.canListHistory) {\n      this.loadedHistory.add(agentId);\n      return;","sourceCodeStart":400,"sourceCodeEnd":436,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/agents/source.ts#L400-L436","documentation":"persistSnapshot writes the agent snapshot file through the source provider; before writing it re-checks getCapabilities() and throws if canWrite=false (or the provider's specific reason). Snapshots back agent versioning, so a write-incapable provider cannot support create/version operations.","triggerScenarios":"Calling create() or createVersion() (which persist snapshots) on an agents storage source whose provider reports canWrite=false; also any direct persistSnapshot path.","commonSituations":"Pointing the provider at a read-only mount or read-only filesystem, missing write permissions/credentials, using a read-only provider class, disk quota or immutable storage (e.g. read-only S3 policy).","solutions":["Read capabilities.reason from the thrown message and fix that specific condition","Grant write permissions/credentials on the target location","Switch to a provider backed by writable storage","Remount/relax read-only configuration (e.g. rw mount, writable bucket policy)"],"exampleFix":"// before\nnew LocalFileSourceProvider({ root: '/ro-mount/agents' }) // read-only fs\n// after\nnew LocalFileSourceProvider({ root: './.mastra/agents' }) // writable","handlingStrategy":"validation","validationCode":"const caps = await provider.getCapabilities();\nif (!caps.canWrite) throw new Error(caps.reason ?? 'provider cannot write files');","typeGuard":"function canWrite(caps: { canWrite: boolean }): caps is { canWrite: true } { return caps.canWrite === true; }","tryCatchPattern":"try {\n  await storage.agents.create({ agent });\n} catch (e) {\n  if (e.message.includes('cannot write files')) { /* switch provider or fix perms */ }\n  throw e;\n}","preventionTips":["Verify write access to the target path/mount before configuring","Avoid read-only mounts and read-only bucket policies for source providers","Run a probe write in deployment checks","Include provider-specific capabilities.reason for diagnostics"],"tags":["storage","agents","permissions","source-provider","write"],"backgroundTag":"readonly-filesystem","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}