{"record":{"id":"456b0781d4fcc59a","repo":"eyaltoledano/claude-task-master","slug":"workflow-already-exists-use-force-true-to-overrid","errorCode":null,"errorMessage":"Workflow already exists. Use force=true to override or resume existing workflow.","messagePattern":"Workflow already exists\\. Use force=true to override or resume existing workflow\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/tm-core/src/modules/workflow/services/workflow.service.ts","lineNumber":171,"sourceCode":"\t}\n\n\t/**\n\t * Start a new TDD workflow\n\t */\n\tasync startWorkflow(options: StartWorkflowOptions): Promise<WorkflowStatus> {\n\t\tconst {\n\t\t\ttaskId,\n\t\t\ttaskTitle,\n\t\t\tsubtasks,\n\t\t\tmaxAttempts = 3,\n\t\t\tforce,\n\t\t\ttag,\n\t\t\torgSlug\n\t\t} = options;\n\n\t\t// Check for existing workflow\n\t\tif ((await this.hasWorkflow()) && !force) {\n\t\t\tthrow new Error(\n\t\t\t\t'Workflow already exists. Use force=true to override or resume existing workflow.'\n\t\t\t);\n\t\t}\n\n\t\t// Initialize git adapter and ensure clean state\n\t\tconst gitAdapter = new GitAdapter(this.projectRoot);\n\t\tawait gitAdapter.ensureGitRepository();\n\t\tawait gitAdapter.ensureCleanWorkingTree();\n\n\t\t// Parse subtasks to WorkflowContext format\n\t\tconst workflowSubtasks: SubtaskInfo[] = subtasks.map((st) => ({\n\t\t\tid: st.id,\n\t\t\ttitle: st.title,\n\t\t\tstatus: st.status === 'done' ? 'completed' : 'pending',\n\t\t\tattempts: 0,\n\t\t\tmaxAttempts: st.maxAttempts || maxAttempts\n\t\t}));\n","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/packages/tm-core/src/modules/workflow/services/workflow.service.ts#L153-L189","documentation":"startWorkflow() refuses to create a new TDD workflow when a workflow state file already exists for the project and the caller did not pass force=true. The state file represents a live or interrupted workflow; silently overwriting it could lose progress. The error tells you to either override with force or resume the existing workflow instead.","triggerScenarios":"Calling workflowService.startWorkflow(options) (or the `start` CLI/MCP command) when stateManager.exists() returns true (a previous workflow was started and its state file persists in .taskmaster/workflow or equivalent) and options.force is not true.","commonSituations":"Re-running `taskmaster start` after a previous run crashed without cleanup; switching branches or pulling changes without finishing the prior workflow; running start from a repo where a teammate's or CI's state file was committed; forgetting that a workflow was already started on the same task days earlier.","solutions":["Call resumeWorkflow() (or the `resume` command) to continue the existing workflow instead of starting over.","Pass force: true in StartWorkflowOptions to discard the existing state and start fresh.","Manually remove the persisted workflow state file (in the project's workflow state directory) if it is stale and you do not need it.","Check getStatus()/hasWorkflow() before calling startWorkflow to decide programmatically between resume and force."],"exampleFix":"// before\nawait workflowService.startWorkflow({ taskId: '1', taskTitle: 'X', subtasks });\n// after\nif (await workflowService.hasWorkflow()) {\n  await workflowService.resumeWorkflow();\n} else {\n  await workflowService.startWorkflow({ taskId: '1', taskTitle: 'X', subtasks });\n}\n// or intentionally override:\nawait workflowService.startWorkflow({ taskId: '1', taskTitle: 'X', subtasks, force: true });","handlingStrategy":"validation","validationCode":"if (await workflowService.hasWorkflow()) {\n  // decide: resume or force\n  await workflowService.resumeWorkflow(); // or startWorkflow({...,force:true})\n} else {\n  await workflowService.startWorkflow(options);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await workflowService.startWorkflow(options);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Workflow already exists')) {\n    await workflowService.resumeWorkflow(); // continue existing work\n  } else {\n    throw err;\n  }\n}","preventionTips":["Always check hasWorkflow()/getStatus() before calling startWorkflow.","Never commit or sync the workflow state directory between machines or branches.","Finish or explicitly force-reset workflows before starting new ones on the same repo.","Add force: true only after confirming the existing state is stale."],"tags":["workflow","duplicate-state","conflict"],"backgroundTag":"workflow-already-exists","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}