{"record":{"id":"ba7ddd491710ecdf","repo":"mastra-ai/mastra","slug":"resolved-reason","errorCode":null,"errorMessage":"${resolved.reason}","messagePattern":"\\$\\{resolved\\.reason\\}","errorType":"exception","errorClass":"FactorySourceSessionResolutionError","httpStatus":null,"severity":"error","filePath":"mastracode/factory/src/session/factory-session.ts","lineNumber":193,"sourceCode":" * `FactoryStartCoordinator.prepare` requires this record to already exist —\n * `resolveSourceSession` throws `Factory session not found` otherwise — so every\n * autonomous entry point has to produce one before it can start a run. This is\n * that step, in one place: the owner's connection on the factory project, one of\n * its linked repositories, and a session on the requested branch with the\n * repository's pinned or default branch as the base.\n *\n * The run is attributed to `attributeToUserId` when the caller has an\n * interactive user (e.g. the approver of a proposed run), and otherwise falls\n * back to whoever connected the repository (`connection.createdByUserId`),\n * because a genuinely autonomous run has no interactive user of its own.\n */\nexport async function ensureFactorySourceSession(\n  args: EnsureFactorySourceSessionArgs,\n): Promise<EnsuredFactorySourceSession> {\n  const { sourceControl, orgId, factoryProjectId, branch, repositorySlug } = args;\n\n  const resolved = await resolveFactorySourceRepository({ sourceControl, orgId, factoryProjectId, repositorySlug });\n  if (!resolved.found) throw new FactorySourceSessionResolutionError(resolved.reason);\n\n  const userId = args.attributeToUserId ?? resolved.connectedByUserId;\n  const session = await sourceControl.sessions.create({\n    sessionId: randomUUID(),\n    projectRepositoryId: resolved.projectRepositoryId,\n    orgId,\n    userId,\n    branch,\n    baseBranch: resolved.baseBranch,\n    visibility: 'org',\n  });\n  return {\n    sessionId: session.sessionId,\n    userId,\n    projectRepositoryId: resolved.projectRepositoryId,\n    branch: session.branch,\n    baseBranch: resolved.baseBranch,\n  };","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/session/factory-session.ts#L175-L211","documentation":"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.).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check resolved.reason in the FactorySourceSessionResolutionError for the exact cause","Verify the source-control app is installed on the org and the repository is linked to the factory project","Confirm orgId and factoryProjectId match the project's actual settings","Correct the repositorySlug (owner/name) spelling and casing"],"exampleFix":"// before\nawait ensureFactorySourceSession({ sourceControl, orgId: otherOrg, factoryProjectId, branch, repositorySlug });\n// after\nconst resolved = await resolveFactorySourceRepository({ sourceControl, orgId, factoryProjectId, repositorySlug });\nif (!resolved.found) throw new Error(`Repo not linked: ${resolved.reason}`);\nawait ensureFactorySourceSession({ sourceControl, orgId, factoryProjectId, branch, repositorySlug });","handlingStrategy":"try-catch","validationCode":"const resolved = await resolveFactorySourceRepository({ sourceControl, orgId, factoryProjectId, repositorySlug });\nif (!resolved.found) throw new Error(`Cannot start factory session: ${resolved.reason}`);","typeGuard":"function isResolvedRepo(r: { found: boolean; reason?: string }): r is { found: true } & Record<string, unknown> {\n  return r.found === true;\n}","tryCatchPattern":"try {\n  await ensureFactorySourceSession(args);\n} catch (e) {\n  if (e instanceof FactorySourceSessionResolutionError) {\n    logger.warn('factory source unresolved', { reason: e.message });\n    // surface resolved.reason to the user / prompt for repo linking\n  } else throw e;\n}","preventionTips":["Always pre-check with resolveFactorySourceRepository before creating sessions","Keep the source-control app installed on the org and repos","Validate repositorySlug format (owner/repo) before calls","Log resolved.reason to diagnose linkage failures"],"tags":["source-control","session","resolution"],"backgroundTag":"factory-source-resolution-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}