mastra-ai/mastra · error · FactoryDispatchError

source_control_missing_or_source_repository_missing

source_control_missing_or_source_repository_missing

Error message

error.message (dynamic; FactorySourceSessionResolutionError)

What it means

When binding a factory rule, resolving the source-control session can fail with FactorySourceSessionResolutionError. If the resolution reason is not 'connection' (i.e. the repository itself is missing/unresolvable), the error is rethrown as FactoryDispatchError with code 'source_repository_missing', keeping the original message. It signals the source repository referenced by the work item can't be located.

Solutions

Verify the repository referenced by item.metadata.repository exists and the slug is spelled correctly.
Check the source-control connection has access to that repository (permissions/org membership).
Inspect the original FactorySourceSessionResolutionError (attached as `cause`) for details.
Update the board rule or item metadata to reference the correct repository.

Example fix

// before
repositorySlug: item.metadata?.repository // 'acme/old-repo' (renamed)
// after
repositorySlug: item.metadata?.repository === 'acme/old-repo'
  ? 'acme/new-repo'
  : item.metadata?.repository

Defensive patterns

Strategy: try-catch

Validate before calling

const repo = item.metadata?.repository;
const repoKnown = typeof repo === 'string' && repo.length > 0 && (await repoExistsInConnection(repo));
if (!repoKnown) skipBinding(item);

Type guard

function hasRepositoryMetadata(item: { metadata?: { repository?: unknown } }): item is { metadata: { repository: string } } {
  return typeof item.metadata?.repository === 'string' && item.metadata.repository !== '';
}

Try / catch

try {
  await prepareFactoryRuleBinding(input);
} catch (e) {
  if (e instanceof FactoryDispatchError && e.code === 'source_repository_missing') {
    logger.warn('Repository not found for rule binding', { cause: e.cause, repo: input.item.metadata?.repository });
  } else throw e;
}

Prevention

Keep item.metadata.repository slugs in sync with actual repo names (watch renames/archives).
Verify the source-control connection grants access to the referenced repository.
Include the cause chain when logging so the original FactorySourceSessionResolutionError is visible.

When it happens

Trigger: A rule binding whose item points to a repository slug/repo metadata that doesn't exist or isn't accessible in the resolved source-control session; FactorySourceSessionResolutionError thrown with reason other than 'connection'.

Common situations: Renamed/deleted repositories; metadata.repository strings that don't match the actual slug; wrong tenant/connection owning the repo; typo'd repo config in the board rule.

Related errors

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

Appendix: source

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

      destinationStage,
      workItem: {
        id: input.item.id,
        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(

View on GitHub (pinned to 75dd419e61)