API key must be - UTF-8 bytes

Error message

API key must be {MIN_API_KEY_BYTES}-{MAX_API_KEY_BYTES} UTF-8 bytes

What it means

validate_api_key enforces that a Codewhale API key falls within the allowed byte-length range (MIN_API_KEY_BYTES..MAX_API_KEY_BYTES). The CLI bails before sending anything to the server when the provided key string is too short or too long. This is a client-side guard so a truncated or mangled paste fails fast locally instead of producing a server 401.

Solutions

Re-copy the full API key and pass it again, checking its length matches the documented format
Inspect the value with `echo -n "$KEY" | wc -c` to confirm byte count before retrying
If input comes from a file or stdin, ensure no stray bytes (e.g. concatenated lines) were included
Create a fresh key with `codewhale account api-keys create` if the original is unrecoverable

Example fix

// before
codewhale account api-keys import --api-key "cwc_key_abc123"  # truncated
// after
codewhale account api-keys import --api-key "cwc_key_0a1b...<24 hex>_<43 chars>"

Defensive patterns

Strategy: validation

Validate before calling

fn key_len_ok(key: &str, min: u64, max: u64) -> bool {
    let n = key.len() as u64;
    n >= min && n <= max
}
// call before import: if !key_len_ok(&key, MIN, MAX) { /* fix input */ }

Type guard

fn is_plausible_api_key(s: &str) -> bool {
    s.starts_with("cwc_key_") && s.len() >= 32 && s.len() <= 256
}

Prevention

Store keys in a file/secret manager and pass via --api-key-stdin (it trims and validates)
Check byte count with `wc -c` before importing a key
Never hand-edit a key token; copy it whole from `codewhale account api-keys list`

When it happens

Trigger: Calling the CLI's api-key import/creation paths (validate_api_key in crates/cli/src/cloud.rs:1135) with a --api-key value whose UTF-8 byte length is below MIN_API_KEY_BYTES or above MAX_API_KEY_BYTES.

Common situations: Pasting only part of a key (truncated clipboard), shell quoting stripping characters, an extra file or whitespace appended making the value too long, or copying a different provider's key that has a different length.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at crates/cli/src/cloud.rs:1135

    }
    Ok(())
}

fn validate_device_code(code: &str) -> Result<()> {
    if code.len() != 43
        || !code
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
    {
        bail!("The Codewhale service returned an invalid device authorization response");
    }
    Ok(())
}

fn validate_api_key(key: &str) -> Result<()> {
    let bytes = key.len();
    if bytes < MIN_API_KEY_BYTES || bytes as u64 > MAX_API_KEY_BYTES {
        bail!("API key must be {MIN_API_KEY_BYTES}-{MAX_API_KEY_BYTES} UTF-8 bytes");
    }
    if key.chars().any(is_ascii_control) {
        bail!("API key contains invalid control characters");
    }
    Ok(())
}

fn validate_label(label: &str) -> Result<String> {
    let label = label.split_whitespace().collect::<Vec<_>>().join(" ");
    if label.is_empty()
        || label.chars().count() > MAX_KEY_LABEL_CHARS
        || label.chars().any(is_ascii_control)
    {
        bail!("key label must contain 1-{MAX_KEY_LABEL_CHARS} characters");
    }
    Ok(label)
}

View on GitHub (pinned to 73e0f67d83)