mastra-ai/mastra · error · Error

Source provider ${this.provider.displayName} cannot write fi

Error message

Source provider ${this.provider.displayName} cannot write files

What it means

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.

Source

Thrown at packages/core/src/storage/domains/agents/source.ts:418

  private getCodeDefinedAgent(agentId: string): { source?: string; __getEditorConfig?: () => unknown } | undefined {
    try {
      const agent = this.storageMastra?.getAgentById?.(agentId) as
        | { source?: string; __getEditorConfig?: () => unknown }
        | undefined;
      return agent?.source === 'code' ? agent : undefined;
    } catch {
      return undefined;
    }
  }

  private async persistSnapshot(
    agentId: string,
    snapshot: Record<string, unknown>,
    message?: string,
  ): Promise<SourceWriteResult> {
    const capabilities = await this.provider.getCapabilities();
    if (!capabilities.canWrite) {
      throw new Error(capabilities.reason ?? `Source provider ${this.provider.displayName} cannot write files`);
    }
    const agent = this.getCodeDefinedAgent(agentId);
    const filtered = filterSourceSnapshot(snapshot, agent?.__getEditorConfig?.(), Boolean(agent));
    return this.provider.writeFile({
      path: getSourceAgentFilePath(agentId),
      ref: this.activeRefs.get(agentId),
      content: `${stableStringify(filtered)}\n`,
      message,
    });
  }

  private async loadHistory(agentId: string): Promise<void> {
    if (this.loadedHistory.has(agentId)) return;

    const capabilities = await this.provider.getCapabilities();
    if (!capabilities.canListHistory) {
      this.loadedHistory.add(agentId);
      return;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read capabilities.reason from the thrown message and fix that specific condition
2. Grant write permissions/credentials on the target location
3. Switch to a provider backed by writable storage
4. Remount/relax read-only configuration (e.g. rw mount, writable bucket policy)

Example fix

// before
new LocalFileSourceProvider({ root: '/ro-mount/agents' }) // read-only fs
// after
new LocalFileSourceProvider({ root: './.mastra/agents' }) // writable

const caps = await provider.getCapabilities();
if (!caps.canWrite) throw new Error(caps.reason ?? 'provider cannot write files');

function canWrite(caps: { canWrite: boolean }): caps is { canWrite: true } { return caps.canWrite === true; }

try {
  await storage.agents.create({ agent });
} catch (e) {
  if (e.message.includes('cannot write files')) { /* switch provider or fix perms */ }
  throw e;
}

When it happens

Trigger: Calling create() or createVersion() (which persist snapshots) on an agents storage source whose provider reports canWrite=false; also any direct persistSnapshot path.

Common situations: 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).

Related errors

• Source provider ${this.provider.displayName} cannot read fil
• Failed to write scorer: ${errorMessage}
• Agent with id ${input.agent.id} already exists
• Version with id ${input.id} already exists
• Version number ${input.versionNumber} already exists for age

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/e006746170457666. Report an issue: GitHub.