Hmbown/CodeWhale · error

a reserved turn id requires an operation key

Error message

a reserved turn id requires an operation key

What it means

start_turn guard: a reserved turn id was supplied without an operation key; reservations exist to support idempotent operation-key replay, so a reservation alone is an invalid combination rejected before any persistence.

Solutions

1. Pass a non-empty prompt in the StartTurnRequest.
2. Use the continuation/goal prompt path (start_goal_turn) if the intent is an automatic continuation.

When it happens

Trigger: Thrown at crates/tui/src/runtime_threads.rs:9759 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/e423f137d0cbe5f9. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/runtime_threads.rs:9759

    async fn start_turn_inner(
        &self,
        thread_id: &str,
        req: StartTurnRequest,
        reserved_turn_id: Option<&str>,
    ) -> Result<TurnRecord> {
        self.start_turn_inner_reporting_replay(thread_id, req, reserved_turn_id)
            .await
            .map(|(turn, _replayed)| turn)
    }

    async fn start_turn_inner_reporting_replay(
        &self,
        thread_id: &str,
        req: StartTurnRequest,
        reserved_turn_id: Option<&str>,
    ) -> Result<(TurnRecord, bool)> {
        if reserved_turn_id.is_some() && req.operation_key.is_none() {
            bail!("a reserved turn id requires an operation key");
        }
        self.start_turn_with_source(
            thread_id,
            req,
            RuntimeTurnInputSource::ExternalUser,
            reserved_turn_id,
            false,
        )
        .await
    }

    /// Retry only bytes recovered from validated durable history. This internal
    /// entry point changes the historical byte ceiling, never model or policy
    /// admission, and cannot be selected by a network request field.
    pub(crate) async fn start_turn_from_stored_images(
        &self,
        thread_id: &str,
        req: StartTurnRequest,

View on GitHub (pinned to 73e0f67d83)