eyaltoledano/claude-task-master · error

Unknown TDD phase: ${tddPhase}

Error message

Unknown TDD phase: ${tddPhase}

What it means

completePhase() switches on the current TDD phase and only recognizes RED, GREEN, and COMMIT. Any other value (e.g. a phase string from a newer/older state file or an internal state-machine bug) falls into the default branch and throws 'Unknown TDD phase: <value>'. This should be unreachable with valid state and usually indicates corrupted or version-skewed persisted state.

Source

Thrown at packages/tm-core/src/modules/workflow/services/workflow.service.ts:447

		switch (tddPhase) {
			case 'RED':
				await this.orchestrator.transition({
					type: 'RED_PHASE_COMPLETE',
					testResults
				});
				break;
			case 'GREEN':
				await this.orchestrator.transition({
					type: 'GREEN_PHASE_COMPLETE',
					testResults
				});
				break;
			case 'COMMIT':
				throw new Error(
					'Cannot complete COMMIT phase with test results. Use commit() instead.'
				);
			default:
				throw new Error(`Unknown TDD phase: ${tddPhase}`);
		}

		return this.getStatus();
	}

	/**
	 * Commit current changes and advance workflow
	 */
	async commit(): Promise<WorkflowStatus> {
		if (!this.orchestrator) {
			throw new Error('No active workflow. Start or resume a workflow first.');
		}

		const tddPhase = this.orchestrator.getCurrentTDDPhase();

		if (tddPhase !== 'COMMIT') {
			throw new Error(
				`Cannot commit in ${tddPhase} phase. Complete RED and GREEN phases first.`

View on GitHub (pinned to c0c98d367c)

Solutions

1. Abort the stale workflow (abortWorkflow()) or delete the state file and start a new one with startWorkflow()
2. Check for a package version mismatch: upgrade/downgrade @tm/core so it matches the version that wrote the state
3. Inspect the persisted workflow state file for a corrupted tddPhase value
4. If reproducible on current versions, report a bug with the state file and the logged phase value

Example fix

// before
await workflowService.completePhase(results); // throws Unknown TDD phase: LEGACY
// after
try {
  await workflowService.completePhase(results);
} catch (e) {
  if (String(e.message).startsWith('Unknown TDD phase')) {
    await workflowService.abortWorkflow();
    await workflowService.startWorkflow(taskConfig); // fresh state
  } else throw e;
}

const tdd = workflowService.getStatus().tddPhase;
const known = ['RED','GREEN','COMMIT'].includes(tdd as string);
if (!known) {
  // stale/corrupt state from another version: abort and restart
  await workflowService.abortWorkflow();
}

function isKnownTddPhase(v: unknown): v is 'RED'|'GREEN'|'COMMIT' {
  return v === 'RED' || v === 'GREEN' || v === 'COMMIT';
}

try {
  await workflowService.completePhase(results);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown TDD phase')) {
    await workflowService.abortWorkflow();
    await workflowService.startWorkflow(taskConfig); // fresh valid state
  } else throw e;
}

When it happens

Trigger: Resuming a workflow whose persisted state contains a TDD phase value the current code does not recognize (version mismatch between saved state and library version); a corrupted .taskmaster/workflow state file; internal state machine regression producing an unexpected phase value.

Common situations: Upgrading the package while a workflow state file from the old version is still on disk; hand-editing or partial writes to the state file; plugin/custom transitions injecting unknown phase values.

Related errors

• 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
• Invalid transition: COMMIT_COMPLETE from non-COMMIT phase

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