What causes "unknown key notation: " in xai-org/grok-build?

Use a supported notation, e.g. , , , , –

unknown key notation: <{notation}>

Error message

unknown key notation: <{notation}>

What it means

parse_special() converts special key notations like <ctrl-a>, <enter>, <f1> into key events. Notations it doesn't recognize (and that aren't handled elsewhere in parse_to_events) raise this error.

Source

Thrown at crates/codegen/ptyctl/src/keys.rs:144

        "f9" => KeyCode::F(9),
        "f10" => KeyCode::F(10),
        "f11" => KeyCode::F(11),
        "f12" => KeyCode::F(12),
        "lt" => KeyCode::Char('<'),
        "gt" => KeyCode::Char('>'),
        "bar" => KeyCode::Char('|'),
        "bslash" => KeyCode::Char('\\'),
        s if s.len() == 1 => {
            let c = s.chars().next().unwrap();
            // For Shift+letter with no other modifiers, uppercase it (vim behavior).
            if modifiers == KeyModifiers::SHIFT && c.is_ascii_alphabetic() {
                modifiers = KeyModifiers::NONE;
                KeyCode::Char(c.to_ascii_uppercase())
            } else {
                KeyCode::Char(c)
            }
        }
        _ => bail!("unknown key notation: <{notation}>"),
    };

    Ok(key(code, modifiers))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_literal_text() {
        let bytes = parse_keys("hello").unwrap();
        assert_eq!(bytes, b"hello");
    }

    #[test]
    fn test_enter() {
        let bytes = parse_keys("<CR>").unwrap();

View on GitHub (pinned to bc7f02eddd)

Solutions

Use a supported notation, e.g. <ctrl-a>, <enter>, <esc>, <tab>, <f1>–<f12>
Fix typos like <cntl-a> → <ctrl-a>
Send plain characters without angle brackets for regular text
Check keys.rs parse_special for the exact list of accepted notations

Example fix

// before
ptyctl keys --name dev '<cntl-c>'
// after
ptyctl keys --name dev '<ctrl-c>'

Defensive patterns

Strategy: validation

Validate before calling

fn is_known_special(notation: &str) -> bool {
    matches!(notation, "enter" | "esc" | "tab" | "backspace" | "space" | "up" | "down" | "left" | "right" | "ctrl-a" | "ctrl-c" | "ctrl-d")
        || notation.starts_with("f") // function keys
}

Try / catch

match parse_to_events(input) {
    Ok(events) => send(events),
    Err(e) if e.to_string().contains("unknown key notation") => {
        eprintln!("bad key spec; see docs for supported <...> notations");
    }
    Err(e) => return Err(e),
}

Prevention

Keep a cheat-sheet of supported <...> notations
Lint test scripts for common typos (<cntl vs <ctrl>)
Send plain characters for text, angle brackets only for special keys
Check keys.rs for the authoritative notation list

When it happens

Trigger: Passing a key string containing `<...>` whose inner text is not a supported special key (e.g. <command-a>, <hyper-x>, <foo>) to the keys command/API.

Common situations: Typo in a key name (<cntl-a> instead of <ctrl-a>); using platform-specific modifier names the parser doesn't know; copy-pasting notations from another tool's syntax.

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/48a39a782ad9c5df. Report an issue: GitHub.