{"record":{"id":"a4f032a5a041e327","repo":"vercel/ai","slug":"harnessid-cannot-start-a-new-acp-prompt-while-a","errorCode":null,"errorMessage":"${harnessId} cannot start a new ACP prompt while a turn is in flight.","messagePattern":"(.+?) cannot start a new ACP prompt while a turn is in flight\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/acp-v1-harness.ts","lineNumber":1457,"sourceCode":"        mcpServers,\n        debug,\n        authenticationProfile,\n        sessionMeta,\n        instructionMapping,\n        responseFormat: options.responseFormat,\n        outputSchemaMapping,\n        model,\n        modelMapping,\n      });\n      const nextInstructionsFingerprint = fingerprintValue({\n        value: options.instructions ?? null,\n      });\n      const control = wireTurn({\n        emit: options.emit,\n        abortSignal: options.abortSignal,\n        start: () => {\n          if (turnInFlight) {\n            throw new Error(\n              `${harnessId} cannot start a new ACP prompt while a turn is in flight.`,\n            );\n          }\n          turnInFlight = true;\n          channel.send({\n            type: 'start',\n            prompt:\n              instructionsFingerprint !== nextInstructionsFingerprint &&\n              (instructionMapping == null || initialGuidanceApplied)\n                ? prependACPInstructionGuidance({\n                    prompt,\n                    instructions: options.instructions,\n                  })\n                : prompt,\n            ...(instructionMapping == null\n              ? {}\n              : {\n                  instructionMapping,","sourceCodeStart":1439,"sourceCodeEnd":1475,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/acp-v1-harness.ts#L1439-L1475","documentation":"The ACP harness serializes one turn per session: when doPromptTurn's start callback fires and a turn is already in flight (turnInFlight=true), it refuses to send another 'start' message over the channel. ACP sessions process a single prompt at a time, so concurrent prompts on the same session are rejected.","triggerScenarios":"Calling promptTurn on the same session while a previous turn has not completed (no done event yet), including calling promptTurn again before awaiting the prior turn's completion or firing it from a concurrent async task.","commonSituations":"Race conditions where two parts of an app both send prompts to one session; not awaiting the previous promptTurn promise; UI retry logic double-firing a submit; a long-running turn still streaming when a follow-up prompt is issued.","solutions":["Await the previous promptTurn completion (or its done/error event) before starting a new turn on the same session.","Gate prompt submissions behind a per-session busy flag/mutex so only one turn is ever in flight.","Queue additional prompts and dispatch them sequentially after the current turn finishes.","Create a separate session if you genuinely need parallel turns."],"exampleFix":"// before\nsession.promptTurn({ prompt });\nsession.promptTurn({ prompt2 }); // throws: turn in flight\n// after\nawait session.promptTurn({ prompt });\nawait session.promptTurn({ prompt2 });","handlingStrategy":"validation","validationCode":"let busy = false;\nasync function safePrompt(session, opts) {\n  if (busy) throw new Error('turn already in flight');\n  busy = true;\n  try { return await session.promptTurn(opts); } finally { busy = false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await session.promptTurn({ prompt });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('while a turn is in flight')) {\n    await enqueuePrompt(prompt); // retry after current turn completes\n  } else throw e;\n}","preventionTips":["Always await promptTurn before issuing the next prompt on the same session","Serialize prompts per session with a mutex/queue","Use one session per concurrent workload instead of sharing one"],"tags":["acp","concurrency","turn-in-flight","session-state"],"backgroundTag":"concurrent-turn-not-allowed","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}