eyaltoledano/claude-task-master · error

Guard condition failed for transition to ${transition.to}

Error message

Guard condition failed for transition to ${transition.to}

What it means

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.

Source

Thrown at packages/tm-core/src/modules/workflow/orchestrators/workflow-orchestrator.ts:302

				this.emit('phase:entered');
				// Note: Don't auto-transition to COMPLETE - requires explicit finalize call
				break;

			default:
				throw new Error(`Invalid transition: ${event.type} in SUBTASK_LOOP`);
		}
	}

	/**
	 * Execute a state transition
	 */
	private executeTransition(
		transition: StateTransition,
		event: WorkflowEvent
	): void {
		// Check guard condition if present
		if (transition.guard && !transition.guard(this.context)) {
			throw new Error(
				`Guard condition failed for transition to ${transition.to}`
			);
		}

		// Check phase-specific guard if present
		const phaseGuard = this.phaseGuards.get(transition.to);
		if (phaseGuard && !phaseGuard(this.context)) {
			throw new Error('Guard condition failed');
		}

		// Emit phase exit event
		this.emit('phase:exited');

		// Update context based on event
		this.updateContext(event);

		// Transition to new phase
		this.currentPhase = transition.to;

View on GitHub (pinned to c0c98d367c)

Solutions

1. 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().
2. Ensure the workflow phases run in the correct order so the guarded precondition is satisfied (e.g. complete BRANCH_SETUP before entering SUBTASK_LOOP).
3. If resuming, delete the stale workflow state file and start a fresh workflow with startWorkflow().
4. If the guard is genuinely outdated for your flow, relax or replace the guard function when constructing/registering transitions.

Example fix

// before
await orchestrator.transition({ type: 'BRANCH_CREATED', branchName: undefined });
// after
const branchName = await gitAdapter.createAndCheckoutBranch(name);
if (!branchName) throw new Error('branch creation failed');
await orchestrator.transition({ type: 'BRANCH_CREATED', branchName });

const ctx = orchestrator.getContext();
const transition = getTransitionFor(event.type); // your transition lookup
if (transition?.guard && !transition.guard(ctx)) {
  throw new Error(`Pre-check: guard for -> ${transition.to} would fail; ctx=${JSON.stringify(ctx)}`);
}

try {
  await orchestrator.transition(event);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Guard condition failed for transition to')) {
    console.error(`Transition to ${event.type} blocked by guard: ${err.message}. Fix context before retrying.`);
    return; // do not retry blindly; repair context first
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Guard condition failed
• Workflow has been aborted
• Invalid transition: ${event.type} from ${this.currentPhase}
• Invalid transition: RED_PHASE_COMPLETE from non-RED phase
• Invalid transition: GREEN_PHASE_COMPLETE from non-GREEN phas

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/e5ba31fc00a30129. Report an issue: GitHub.