mastra-ai/mastra · error · Error

Source provider ${this.provider.displayName} cannot read fil

Error message

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

What it means

During MastraStorage source-domain initialization, the storage backend asks its configured source provider whether it can read files (getCapabilities). If the provider reports canRead=false, init() aborts with this error (or the provider's more specific reason text). This guards against wiring a write-only or otherwise unsuitable provider as an agent source.

Source

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

  private readonly loadedHistory = new Set<string>();
  private readonly hydratedAgents = new Set<string>();
  private readonly activeRefs = new Map<string, string>();
  private providerAgentIdsDiscovered = false;

  constructor({ provider, agentIds = [] }: SourceAgentsSourceControlConfig) {
    super();
    this.provider = provider;
    this.knownAgentIds = new Set(agentIds);
  }

  __registerMastra(mastra: StorageMastraRef): void {
    this.storageMastra = mastra;
  }

  override async init(): Promise<void> {
    const capabilities = await this.provider.getCapabilities();
    if (!capabilities.canRead) {
      throw new Error(capabilities.reason ?? `Source provider ${this.provider.displayName} cannot read files`);
    }
    this.refreshKnownAgentIds();
    await this.discoverProviderAgentIds();
    await Promise.all([...this.knownAgentIds].map(agentId => this.hydrateAgent(agentId)));
  }

  async dangerouslyClearAll(): Promise<void> {
    this.hydratedAgents.clear();
    this.loadedHistory.clear();
    this.providerVersions.clear();
    this.activeRefs.clear();
    this.providerAgentIdsDiscovered = false;
    await this.memory.dangerouslyClearAll();
  }

  async useProviderRef(agentId: string, ref: string): Promise<void> {
    this.activeRefs.set(agentId, ref);
    this.hydratedAgents.delete(agentId);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect capabilities.reason in the error message for the provider-specific explanation and fix that underlying issue
2. Replace or reconfigure the source provider with one that supports reading files
3. Fix provider configuration (paths, credentials, scheme) so getCapabilities() reports canRead=true
4. If you only need writes, do not use this provider as a source; use the appropriate storage domain instead

Example fix

// before
new HttpSourceProvider({ url: 'https://example.com/agents' }) // canRead=false
// after
new LocalFileSourceProvider({ root: './agents' }) // supports reads

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

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

try { await source.init(); } catch (e) { if (e.message.includes('cannot read files')) { /* reconfigure provider */ } throw e; }

When it happens

Trigger: Calling init() on the agents storage source when the configured provider's getCapabilities() returns canRead=false, or when capabilities.reason is set (that reason string is thrown instead).

Common situations: Configuring a source provider against a read-only-forbidden location (e.g. an HTTP provider, a provider pointed at an unwritable/unsupported backend), misconfigured credentials causing the provider to report degraded capabilities, or swapping provider implementations that don't support reads.

Related errors

• Source provider ${this.provider.displayName} cannot write fi
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• MastraAuthBetterAuth needs a database to build its own bette
• [Slack] Failed to resolve Mastra storage. Ensure your Mastra

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