{"record":{"id":"e5ba31fc00a30129","repo":"eyaltoledano/claude-task-master","slug":"guard-condition-failed-for-transition-to-transit","errorCode":null,"errorMessage":"Guard condition failed for transition to ${transition.to}","messagePattern":"Guard condition failed for transition to (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/tm-core/src/modules/workflow/orchestrators/workflow-orchestrator.ts","lineNumber":302,"sourceCode":"\t\t\t\tthis.emit('phase:entered');\n\t\t\t\t// Note: Don't auto-transition to COMPLETE - requires explicit finalize call\n\t\t\t\tbreak;\n\n\t\t\tdefault:\n\t\t\t\tthrow new Error(`Invalid transition: ${event.type} in SUBTASK_LOOP`);\n\t\t}\n\t}\n\n\t/**\n\t * Execute a state transition\n\t */\n\tprivate executeTransition(\n\t\ttransition: StateTransition,\n\t\tevent: WorkflowEvent\n\t): void {\n\t\t// Check guard condition if present\n\t\tif (transition.guard && !transition.guard(this.context)) {\n\t\t\tthrow new Error(\n\t\t\t\t`Guard condition failed for transition to ${transition.to}`\n\t\t\t);\n\t\t}\n\n\t\t// Check phase-specific guard if present\n\t\tconst phaseGuard = this.phaseGuards.get(transition.to);\n\t\tif (phaseGuard && !phaseGuard(this.context)) {\n\t\t\tthrow new Error('Guard condition failed');\n\t\t}\n\n\t\t// Emit phase exit event\n\t\tthis.emit('phase:exited');\n\n\t\t// Update context based on event\n\t\tthis.updateContext(event);\n\n\t\t// Transition to new phase\n\t\tthis.currentPhase = transition.to;","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/packages/tm-core/src/modules/workflow/orchestrators/workflow-orchestrator.ts#L284-L320","documentation":"The workflow orchestrator refuses to execute a state transition whose guard predicate returned false. Guards are functions attached to a StateTransition (or registered per-target-phase) that must approve the current WorkflowContext before the phase can change. Throwing here prevents the state machine from entering an inconsistent phase when preconditions are not met.","triggerScenarios":"Calling orchestrator.transition(...) which resolves to a StateTransition that has a `guard` property, where `transition.guard(this.context)` evaluates to false. E.g. calling transition({type: 'BRANCH_CREATED', branchName}) when context lacks expected fields, or PREFLIGHT_COMPLETE when the context doesn't satisfy the guard's checks.","commonSituations":"Registering custom transitions with guards that assume context fields the workflow never populated; resuming a workflow whose persisted context was edited or produced by a different code version so guards no longer hold; running a transition out of order (skipping the phase that would have set the guarded values); branch name missing from context because a git step failed silently earlier.","solutions":["Inspect the guard attached to the transition targeting `transition.to` and check which context field it tests; populate/fix that field in the WorkflowContext before calling transition().","Ensure the workflow phases run in the correct order so the guarded precondition is satisfied (e.g. complete BRANCH_SETUP before entering SUBTASK_LOOP).","If resuming, delete the stale workflow state file and start a fresh workflow with startWorkflow().","If the guard is genuinely outdated for your flow, relax or replace the guard function when constructing/registering transitions."],"exampleFix":"// before\nawait orchestrator.transition({ type: 'BRANCH_CREATED', branchName: undefined });\n// after\nconst branchName = await gitAdapter.createAndCheckoutBranch(name);\nif (!branchName) throw new Error('branch creation failed');\nawait orchestrator.transition({ type: 'BRANCH_CREATED', branchName });","handlingStrategy":"try-catch","validationCode":"const ctx = orchestrator.getContext();\nconst transition = getTransitionFor(event.type); // your transition lookup\nif (transition?.guard && !transition.guard(ctx)) {\n  throw new Error(`Pre-check: guard for -> ${transition.to} would fail; ctx=${JSON.stringify(ctx)}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await orchestrator.transition(event);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Guard condition failed for transition to')) {\n    console.error(`Transition to ${event.type} blocked by guard: ${err.message}. Fix context before retrying.`);\n    return; // do not retry blindly; repair context first\n  }\n  throw err;\n}","preventionTips":["Run transitions only in the documented phase order; never skip setup phases.","Keep guard predicates simple and log which context field they check so failures are diagnosable.","Validate the WorkflowContext (subtasks present, branch set) before each transition call.","Avoid hand-editing persisted workflow state; guards assume schema produced by the library."],"tags":["workflow","state-machine","guard","transition"],"backgroundTag":"state-transition-guard-failed","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}