mastra-ai/mastra · error · FactorySourceSessionResolutionError

${resolved.reason}

Error message

${resolved.reason}

What it means

ensureFactorySourceSession resolves the factory source repository before creating a source-control session. When resolveFactorySourceRepository returns found=false, it throws FactorySourceSessionResolutionError carrying the resolver's reason string. The reason explains why the repository could not be tied to the project (missing connection, repo not registered, access denied, etc.).

Source

Thrown at mastracode/factory/src/session/factory-session.ts:193

 * `FactoryStartCoordinator.prepare` requires this record to already exist —
 * `resolveSourceSession` throws `Factory session not found` otherwise — so every
 * autonomous entry point has to produce one before it can start a run. This is
 * that step, in one place: the owner's connection on the factory project, one of
 * its linked repositories, and a session on the requested branch with the
 * repository's pinned or default branch as the base.
 *
 * The run is attributed to `attributeToUserId` when the caller has an
 * interactive user (e.g. the approver of a proposed run), and otherwise falls
 * back to whoever connected the repository (`connection.createdByUserId`),
 * because a genuinely autonomous run has no interactive user of its own.
 */
export async function ensureFactorySourceSession(
  args: EnsureFactorySourceSessionArgs,
): Promise<EnsuredFactorySourceSession> {
  const { sourceControl, orgId, factoryProjectId, branch, repositorySlug } = args;

  const resolved = await resolveFactorySourceRepository({ sourceControl, orgId, factoryProjectId, repositorySlug });
  if (!resolved.found) throw new FactorySourceSessionResolutionError(resolved.reason);

  const userId = args.attributeToUserId ?? resolved.connectedByUserId;
  const session = await sourceControl.sessions.create({
    sessionId: randomUUID(),
    projectRepositoryId: resolved.projectRepositoryId,
    orgId,
    userId,
    branch,
    baseBranch: resolved.baseBranch,
    visibility: 'org',
  });
  return {
    sessionId: session.sessionId,
    userId,
    projectRepositoryId: resolved.projectRepositoryId,
    branch: session.branch,
    baseBranch: resolved.baseBranch,
  };

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check resolved.reason in the FactorySourceSessionResolutionError for the exact cause
2. Verify the source-control app is installed on the org and the repository is linked to the factory project
3. Confirm orgId and factoryProjectId match the project's actual settings
4. Correct the repositorySlug (owner/name) spelling and casing

Example fix

// before
await ensureFactorySourceSession({ sourceControl, orgId: otherOrg, factoryProjectId, branch, repositorySlug });
// after
const resolved = await resolveFactorySourceRepository({ sourceControl, orgId, factoryProjectId, repositorySlug });
if (!resolved.found) throw new Error(`Repo not linked: ${resolved.reason}`);
await ensureFactorySourceSession({ sourceControl, orgId, factoryProjectId, branch, repositorySlug });

const resolved = await resolveFactorySourceRepository({ sourceControl, orgId, factoryProjectId, repositorySlug });
if (!resolved.found) throw new Error(`Cannot start factory session: ${resolved.reason}`);

function isResolvedRepo(r: { found: boolean; reason?: string }): r is { found: true } & Record<string, unknown> {
  return r.found === true;
}

try {
  await ensureFactorySourceSession(args);
} catch (e) {
  if (e instanceof FactorySourceSessionResolutionError) {
    logger.warn('factory source unresolved', { reason: e.message });
    // surface resolved.reason to the user / prompt for repo linking
  } else throw e;
}

When it happens

Trigger: Calling ensureFactorySourceSession with a sourceControl/orgId/factoryProjectId/repositorySlug combination where the repository cannot be resolved — e.g. repositorySlug not linked to factoryProjectId for that org, GitHub/GitLab app not installed, or wrong orgId.

Common situations: Deploying or resuming a factory run after the repo was unlinked or the source-control integration was revoked; typo'd repositorySlug; pointing at the wrong organization.

Related errors

• Invalid encrypted session data
• Invalid encrypted session data
• [MastraAuthGoogle] GOOGLE_COOKIE_PASSWORD is required for Go
• Session validation failed
• No CDP session available for page

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