mastra-ai/mastra · error

Factory source control storage is unavailable

Error message

Factory source control storage is unavailable

What it means

Thrown at the top of StartCoordinator.prepare when the coordinator was constructed without a source-control storage handle (this.#sourceControl is undefined). Source-control storage is mandatory to resolve the session, repository, and connection graph, so prepare fails fast instead of throwing a confusing null error deeper in resolveSourceSession.

Source

Thrown at mastracode/factory/src/rules/start-coordinator.ts:137

  constructor(
    controller: FactoryController,
    storage: WorkItemsStorage,
    transitionService?: Pick<FactoryTransitionService, 'transition'>,
    sourceControl?: SourceControlStorageHandle,
    memorySettings?: MemorySettingsStorage,
    feedReader?: FactoryFeedReader,
  ) {
    this.#controller = controller;
    this.#storage = storage;
    this.#transitionService = transitionService;
    this.#sourceControl = sourceControl;
    this.#memorySettings = memorySettings;
    this.#feedReader = feedReader;
  }

  async prepare(request: FactoryStartRequest): Promise<FactoryStartPreparedResult> {
    const storage = this.#storage;
    if (!this.#sourceControl) throw new Error('Factory source control storage is unavailable');
    const sourceSession = await resolveSourceSession(this.#sourceControl, request);
    const requestContext = request.requestContext ?? new RequestContext();
    // Factory runs resolve model credentials org > user: the org's shared keys
    // win, with the acting user's personal credentials as a fallback — a board
    // run should never silently prefer whoever kicked it off. The flag rides
    // the stashed user even when a caller-provided context already has one.
    const existingUser = requestContext.get('user');
    if (existingUser && typeof existingUser === 'object') {
      requestContext.set('user', { ...existingUser, orgFirstCredentials: true });
    } else {
      requestContext.set('user', {
        workosId: request.userId,
        organizationId: request.orgId,
        orgFirstCredentials: true,
      });
    }
    // Sessions kicked off against third-party content (a PR under review, or
    // any pull-request-sourced work item) get `untrustedCheckout` so the SDK

View on GitHub (pinned to 75dd419e61)

Solutions

1. Provide the source-control storage handle when constructing the coordinator/factory so this.#sourceControl is defined.
2. Check environment/DI configuration that source-control storage is enabled and wired (storage adapter configured and passed to the rules factory).
3. Before calling start APIs, verify availability via the coordinator's `prepared` accessor and surface a clear configuration error to the operator if it is absent.
4. In tests, construct the coordinator with an in-memory SourceControlStorageHandle rather than omitting it.

Example fix

// before
const coordinator = new StartCoordinator({ storage, memorySettings, feedReader }); // sourceControl missing

// after
const coordinator = new StartCoordinator({
  storage,
  sourceControl: await createSourceControlStorage(config),
  memorySettings,
  feedReader,
});

if (!coordinator.prepared) {
  throw new Error('Start coordinator is not configured with source-control storage; enable factory source-control storage before starting sessions.');
}

function canPrepare(coordinator: StartCoordinator): boolean {
  return coordinator.prepared !== undefined && coordinator.prepared !== null;
}

try {
  const prepared = await coordinator.prepare(request);
} catch (err) {
  if (err instanceof Error && err.message === 'Factory source control storage is unavailable') {
    console.error('Source-control storage not wired into the coordinator; fix DI/config before retrying.');
  }
  throw err;
}

When it happens

Trigger: Instantiating the start coordinator (or the factory rules container wiring it) without providing a sourceControl storage handle — e.g. a deployment or test harness configured without source-control storage enabled — then calling prepare, prepared, preparePromptKickoff, triage, plan, first, or replay.

Common situations: Feature flag for factory/source-control storage disabled in the environment; DI wiring omits the storage dependency; unit tests constructing the coordinator with partial storage; self-hosted setups that skipped the storage configuration step.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Credential storage is not available
• storageBackend is required when injecting a custom storage i
• DURABLE_AGENT_LIST_ACTIVE_RUNS_NO_STORAGE
• Memory requires a storage provider to function. Add a storag
• SCHEDULES_NO_SCHEDULES_STORAGE

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