{"record":{"id":"5758b5ff0ca56efe","repo":"mastra-ai/mastra","slug":"connect-a-repository-before-creating-a-workspace","errorCode":null,"errorMessage":"Connect a repository before creating a workspace","messagePattern":"Connect a repository before creating a workspace","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/factory-ui/src/hooks/useWorkspaces.ts","lineNumber":192,"sourceCode":"    queryKey: queryKeys.userSession(sessionId),\n    queryFn: sessionId ? () => getUserSession(baseUrl, sessionId) : skipToken,\n  });\n}\n\nexport function useCreateWorkspaceMutation(\n  factoryId: string | undefined,\n  projectRepositoryId: string | undefined,\n  scope?: AgentControllerThreadsScope,\n) {\n  const { baseUrl } = useApiConfig();\n  const queryClient = useQueryClient();\n  const navigate = useNavigate();\n\n  return useMutation({\n    mutationFn: async (branch: string) => {\n      const trimmedBranch = branch.trim();\n      if (!factoryId) throw new Error('No Factory selected');\n      if (!projectRepositoryId) throw new Error('Connect a repository before creating a workspace');\n      return createUserSession(baseUrl, projectRepositoryId, { branch: trimmedBranch });\n    },\n    onSuccess: session => {\n      invalidateSessionQueries(queryClient, projectRepositoryId, scope, session.sessionId);\n      void queryClient.invalidateQueries({ queryKey: queryKeys.userSession(session.sessionId) });\n      void navigate(`/factories/${factoryId}/workspaces/${session.sessionId}`);\n    },\n    onError: error => toast.error(error instanceof Error ? error.message : 'Failed to create workspace'),\n  });\n}\n\nexport function useDeleteWorkspaceMutation(\n  factoryId: string | undefined,\n  projectRepositoryId: string | undefined,\n  scope?: AgentControllerThreadsScope,\n) {\n  const { baseUrl } = useApiConfig();\n  const queryClient = useQueryClient();","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory-ui/src/hooks/useWorkspaces.ts#L174-L210","documentation":"In useCreateWorkspaceMutation, after the factoryId check passes, mutationFn throws 'Connect a repository before creating a workspace' when projectRepositoryId is undefined. A workspace is a user session bound to a specific repository, so creating one without a connected repository is rejected client-side.","triggerScenarios":"Calling the create-workspace mutation on a Factory project that has no repository linked yet (projectRepositoryId undefined), e.g. a freshly created project or one where repository connection was revoked/failed.","commonSituations":"New Factory project onboarding where the user skips the 'connect repo' step; repository disconnected by an admin; projectRepositoryId failed to load because the repository settings query errored; user switched factories and the repo id reset to null.","solutions":["Connect a repository in the Factory project settings, then retry workspace creation.","Disable the create-workspace action until projectRepositoryId is present and link to the repository-connection UI from the disabled state.","If the repo should be connected, verify the projectRepositoryId query succeeded and is not stuck loading/error.","After switching factories, confirm the repository id was re-resolved for the new factory."],"exampleFix":"// before\nawait createWorkspace.mutate(branch); // throws if no repo connected\n\n// after\nif (!projectRepositoryId) {\n  navigate(`/factories/${factoryId}/settings/repositories`);\n  return;\n}\nawait createWorkspace.mutate(branch);","handlingStrategy":"validation","validationCode":"if (!projectRepositoryId) {\n  navigate(`/factories/${factoryId}/settings/repositories`);\n  return;\n}","typeGuard":"function hasRepository(id: string | undefined | null): id is string {\n  return typeof id === 'string' && id.length > 0;\n}","tryCatchPattern":"try {\n  await createWorkspace.mutateAsync(branch);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Connect a repository')) {\n    toast.error(e.message);\n    navigate('/settings/repositories');\n  } else throw e;\n}","preventionTips":["Gate workspace creation UI on both factoryId and projectRepositoryId being present.","Show onboarding prompts to connect a repository before offering workspace actions.","Refetch repository settings when switching factories."],"tags":["prerequisite","configuration","factory-ui","react-query"],"backgroundTag":"missing-prerequisite-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}