operation_key cannot exceed

Error message

operation_key cannot exceed {MAX_RUNTIME_TURN_OPERATION_KEY_BYTES} UTF-8 bytes

What it means

validate_runtime_turn_operation_key rejects operation keys that are empty, over MAX_RUNTIME_TURN_OPERATION_KEY_BYTES UTF-8 bytes, have surrounding whitespace, or contain control chars. This check keeps runtime turn operation keys canonical so they can be used as stable identifiers and fingerprinted deterministically across processes.

Solutions

Shorten the operation_key below the byte limit (derive it from a hash or fixed prefix instead of raw long data)
Check MAX_RUNTIME_TURN_OPERATION_KEY_BYTES and assert your key length in code before calling
Trim or normalize key generation to a bounded canonical format

Example fix

// before
let key = format!("turn:{thread_id}:{huge_payload_json}");
// after
let key = format!("turn:{}", sha256_hex(huge_payload_json.as_bytes()));

Defensive patterns

Strategy: validation

Validate before calling

fn ensure_operation_key(key: &str) -> Result<(), String> {
    if key.is_empty() { return Err("empty".into()); }
    if key.len() > MAX_RUNTIME_TURN_OPERATION_KEY_BYTES { return Err("too long".into()); }
    Ok(())
}

Prevention

Generate keys from fixed-width hashes, not raw payloads
Add a debug_assert on key byte length at construction
Never embed unbounded user data in operation keys

When it happens

Trigger: Calling any Runtime turn API that accepts an operation_key (e.g. runtime turn submission in crates/tui/src/runtime_threads.rs) with a string whose UTF-8 byte length exceeds MAX_RUNTIME_TURN_OPERATION_KEY_BYTES.

Common situations: Auto-generated keys that embed long tool names, thread IDs, or payloads; concatenating prefixes such that the key silently grows past the byte cap.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

}

/// Lookup errors deliberately omit operation keys and persisted file paths.
#[derive(Debug, thiserror::Error)]
pub(crate) enum RuntimeTurnOperationLookupError {
    #[error("Invalid thread id or operation key")]
    InvalidRequest,
    #[error("Turn operation acceptance is incomplete; retry lookup")]
    Incomplete,
    #[error("Turn operation lookup unavailable")]
    Unavailable,
}

fn validate_runtime_turn_operation_key(value: &str) -> Result<()> {
    if value.is_empty() {
        bail!("operation_key cannot be empty");
    }
    if value.len() > MAX_RUNTIME_TURN_OPERATION_KEY_BYTES {
        bail!("operation_key cannot exceed {MAX_RUNTIME_TURN_OPERATION_KEY_BYTES} UTF-8 bytes");
    }
    if value.trim() != value {
        bail!("operation_key cannot contain leading or trailing whitespace");
    }
    if value.chars().any(char::is_control) {
        bail!("operation_key cannot contain control characters");
    }
    Ok(())
}

fn validate_sha256_fingerprint(value: &str, label: &str) -> Result<()> {
    if value.len() != 64 || !value.bytes().all(|byte| byte.is_ascii_hexdigit()) {
        bail!("{label} must be a SHA-256 hex digest");
    }
    Ok(())
}

fn runtime_turn_operation_key_fingerprint(

View on GitHub (pinned to 73e0f67d83)