mastra-ai/mastra · error · FactoryDispatchError

source_control_missing

source_control_missing

Error message

error.message (dynamic; SourceControlConnectionNotFoundError)

What it means

If resolving the source-control session fails because no matching source-control connection exists (SourceControlConnectionNotFoundError), prepareFactoryRuleBinding rethrows it as FactoryDispatchError with code 'source_control_missing'. The dynamic message comes from the underlying error describing which connection id/tenant was not found.

Source

Thrown at mastracode/factory/src/routes/surface.ts:233

        role: input.role,
        input: {
          externalSource: input.item.externalSource,
          parentWorkItemId: input.item.parentWorkItemId,
          title: input.item.title,
          stages: ['intake'],
          sessions: input.item.sessions,
          metadata: input.item.metadata,
        },
      },
    });
  } catch (error) {
    if (error instanceof FactoryDispatchError) throw error;
    if (error instanceof FactorySourceSessionResolutionError) {
      const code = error.reason === 'connection' ? 'source_control_missing' : 'source_repository_missing';
      throw new FactoryDispatchError(code, error.message, { cause: error });
    }
    if (error instanceof SourceControlConnectionNotFoundError) {
      throw new FactoryDispatchError('source_control_missing', error.message, { cause: error });
    }
    if (error instanceof MaterializeError) {
      throw new FactoryDispatchError(MATERIALIZE_FAILURE_CODE[error.code], error.message, { cause: error });
    }
    throw error;
  }
}

/**
 * Build the {@link IntegrationContext} handed to an integration when the
 * factory collects its capabilities (routes, workers). One shape everywhere:
 * `assembleFactoryApiRoutes` uses it per registration, and `MastraFactory` uses it
 * when collecting integration workers at finalize.
 */
export function buildIntegrationContext(
  deps: Pick<
    FactoryApiRoutesDeps,
    | 'controller'

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register/reconnect the source-control connection referenced by the rule before dispatching.
2. Verify the connection id in the rule matches an existing connection for the correct tenant/environment.
3. Check the underlying error message (kept as `cause`) for the missing connection identifier.
4. Migrate or recreate board rules after connection rotation so they point at the new connection.

Example fix

// before
await dispatchFactoryRule({ ruleId, connectionId: 'github-old' }); // deleted connection
// after
const connection = await findConnection('github-acme');
if (!connection) throw new Error('Connect the GitHub integration first');
await dispatchFactoryRule({ ruleId, connectionId: connection.id });

const connection = await findSourceControlConnection(connectionId, tenant);
if (!connection) throw new Error(`Source control connection ${connectionId} is not registered for this tenant`);

try {
  await prepareFactoryRuleBinding(input);
} catch (e) {
  if (e instanceof FactoryDispatchError && e.code === 'source_control_missing') {
    logger.error('Source control connection missing; reconnect the integration', { cause: e.cause });
    return Response.json({ error: 'source control not connected', code: 'source_control_missing' }, { status: 409 });
  }
  throw e;
}

When it happens

Trigger: A factory rule references a source-control connection id that was deleted, was never registered, or belongs to another tenant; the connection registry lookup returns nothing for the session resolution request.

Common situations: Rotated or removed integration credentials without updating rules; environment mismatch (rule created in staging, run in prod with different connections); typo'd connection identifier in the rule configuration; connections not yet installed for a newly onboarded tenant.

Related errors

• source_control_missing_or_source_repository_missing
• Factory project not found for this organization.
• Source-control connection not found for this organization.
• GitHub capabilities require a GitHub connection.
• unsupported_provider_item

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