{"record":{"id":"2b12f2619d9c1c5d","repo":"mastra-ai/mastra","slug":"unsupported-factory-stage-stage","errorCode":null,"errorMessage":"Unsupported Factory stage: ${stage}","messagePattern":"Unsupported Factory stage: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/factory-ui/src/hooks/useWorkItems.ts","lineNumber":143,"sourceCode":"    },\n    onError: (_err, _vars, context) => {\n      if (context?.previous) queryClient.setQueryData(listKey, context.previous);\n    },\n    onSuccess: item => {\n      patchCards(queryClient, listKey, cards => cards.map(i => (i.id === item.id ? item : i)));\n    },\n  });\n}\n\ntype TransitionWorkItemVariables = {\n  item: WorkItem;\n  board: FactoryBoard;\n  stage: string;\n  cause?: string;\n};\n\nfunction requireFactoryStage(stage: string): FactoryRuleStage {\n  if (!isFactoryRuleStage(stage)) throw new Error(`Unsupported Factory stage: ${stage}`);\n  return stage;\n}\n\nexport function useTransitionWorkItemMutation(factoryProjectId: string | undefined) {\n  const { baseUrl } = useApiConfig();\n  const queryClient = useQueryClient();\n  const listKey = queryKeys.workItems(factoryProjectId);\n  const mutationKey = ['factory', 'transition-work-item', factoryProjectId] as const;\n  const mutation = useMutation({\n    mutationKey,\n    mutationFn: ({ item, board, stage, cause = 'board_drag' }: TransitionWorkItemVariables) =>\n      transitionWorkItem(baseUrl, requireFactoryProjectId(factoryProjectId), item.id, {\n        board,\n        stage: requireFactoryStage(stage),\n        expectedRevision: item.revision,\n        requestId: crypto.randomUUID(),\n        cause,\n      }),","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory-ui/src/hooks/useWorkItems.ts#L125-L161","documentation":"requireFactoryStage validates that a user-supplied stage string is one of the known FactoryRuleStage values (via isFactoryRuleStage) before a work-item transition mutation is sent. If the stage is not in the allowed union, it throws 'Unsupported Factory stage: <stage>' to prevent invalid board transitions from reaching the server.","triggerScenarios":"Calling the mutation returned by useTransitionWorkItemMutation with variables.stage set to a string that is not a FactoryRuleStage — e.g. a free-text stage from a dropdown, a renamed stage, a typo like 'in-progres', or a stage from a different board's configuration.","commonSituations":"Board stages were customized/renamed on the server but the UI's stage union is stale; dragging a card to a column whose id is not a canonical stage; persisted user preferences referencing an old stage name after a version upgrade.","solutions":["Print/inspect the exact stage value in the error and compare it to the FactoryRuleStage union; correct the caller to use a valid stage.","Update the isFactoryRuleStage guard / stage type union if a new legitimate stage was added server-side.","Constrain the transition UI to a fixed list of valid stages instead of accepting arbitrary strings.","Add a pre-submit validation mapping unknown stages to their canonical equivalents before calling the mutation."],"exampleFix":"// before\nawait transition.mutateAsync({ workItemId, stage: column.id }); // column.id may be arbitrary\n\n// after\nif (!isFactoryRuleStage(column.id)) {\n  toast.error(`Column '${column.id}' is not a valid Factory stage`);\n  return;\n}\nawait transition.mutateAsync({ workItemId, stage: column.id });","handlingStrategy":"validation","validationCode":"if (!isFactoryRuleStage(stage)) {\n  toast.error(`Unsupported stage: ${stage}`);\n  return;\n}","typeGuard":"const FACTORY_STAGES = ['backlog','todo','in_progress','review','done'] as const;\ntype FactoryRuleStage = typeof FACTORY_STAGES[number];\nfunction isFactoryRuleStage(s: string): s is FactoryRuleStage {\n  return (FACTORY_STAGES as readonly string[]).includes(s);\n}","tryCatchPattern":"try {\n  await transition.mutateAsync({ workItemId, stage });\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Unsupported Factory stage')) {\n    toast.error(e.message);\n  } else throw e;\n}","preventionTips":["Drive stage dropdowns from the same typed constant list used by the guard.","Never accept raw column ids from external data without validating against the stage union.","Re-validate persisted stage preferences after upgrades."],"tags":["validation","enum","factory-ui","state-machine"],"backgroundTag":"invalid-enum-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}