{"record":{"id":"ae24ab7b0eee7cbd","repo":"eyaltoledano/claude-task-master","slug":"guard-condition-failed","errorCode":null,"errorMessage":"Guard condition failed","messagePattern":"Guard condition failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/tm-core/src/modules/workflow/orchestrators/workflow-orchestrator.ts","lineNumber":310,"sourceCode":"\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;\n\n\t\t// Emit phase entry event\n\t\tthis.emit('phase:entered');\n\n\t\t// Initialize TDD phase if entering SUBTASK_LOOP\n\t\tif (this.currentPhase === 'SUBTASK_LOOP') {\n\t\t\tthis.context.currentTDDPhase = 'RED';\n\t\t\tthis.emit('tdd:red:started');","sourceCodeStart":292,"sourceCodeEnd":328,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/packages/tm-core/src/modules/workflow/orchestrators/workflow-orchestrator.ts#L292-L328","documentation":"The orchestrator's phase-specific guard for the transition's target phase returned false. Unlike the transition's own guard (error 255), this guard is looked up in the `phaseGuards` map by target phase name, so any transition into that phase is blocked until the WorkflowContext satisfies the registered condition. It throws a generic message and does not name the failing phase, which makes it harder to diagnose.","triggerScenarios":"Calling orchestrator.transition(event) whose resolved StateTransition.to has a guard registered via registerPhaseGuard(to, guard), and `phaseGuard(this.context)` returns false. Same flow as error 255 but the failing check comes from the phaseGuards map, e.g. transitioning into a phase that requires subtasks to be pending or a branch to exist.","commonSituations":"Custom phase guards registered for a phase that assume context state from a different workflow configuration; corrupted/edited persisted state resumed into the orchestrator; event emitted twice so context already advanced past what the guard expects; test code registering strict phase guards then replaying transitions.","solutions":["Find the phaseGuard registered for `transition.to` (search registerPhaseGuard calls) and log/evaluate it manually against the current context to see which condition fails.","Fix the WorkflowContext so the phase guard's condition passes before transitioning (e.g. correct currentSubtaskIndex, subtask statuses, or branchName).","Remove or relax the overly strict phase guard if it no longer matches your workflow semantics.","If state is corrupted, delete the workflow state file and restart with startWorkflow() instead of resumeWorkflow()."],"exampleFix":"// before\norchestrator.registerPhaseGuard('SUBTASK_LOOP', (ctx) => ctx.currentSubtaskIndex === 0);\nawait orchestrator.transition({ type: 'BRANCH_CREATED', branchName }); // resumed at index 2 -> throws\n// after\norchestrator.registerPhaseGuard('SUBTASK_LOOP', (ctx) => ctx.currentSubtaskIndex < ctx.subtasks.length);\nawait orchestrator.transition({ type: 'BRANCH_CREATED', branchName });","handlingStrategy":"try-catch","validationCode":"const ctx = orchestrator.getContext();\nconst targetPhase = resolveTargetPhase(event.type); // phase the transition leads to\n// Re-evaluate the registered phase guard yourself for a precise diagnostic\n// (guardMap is internal, so keep your own mirror of guards you register)\nfor (const [phase, guard] of Object.entries(myRegisteredGuards)) {\n  if (phase === targetPhase && !guard(ctx)) {\n    throw new Error(`Phase guard for ${phase} would fail with current context`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await orchestrator.transition(event);\n} catch (err) {\n  if (err instanceof Error && err.message === 'Guard condition failed') {\n    // Generic message: the failing check is the PHASE guard for transition.to\n    console.error(`Phase guard rejected transition into target phase for event ${event.type}. Inspect phaseGuards and context.`);\n    return;\n  }\n  throw err;\n}","preventionTips":["Keep a named registry of phase guards you register so failures can be traced to a phase quickly.","Write phase guards that tolerate resumed contexts (e.g. currentSubtaskIndex > 0).","Unit-test every phase guard against fresh, mid-progress, and resumed contexts.","Don't register guards for phases you don't transition into."],"tags":["workflow","state-machine","guard","phase"],"backgroundTag":"state-transition-guard-failed","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}