neondatabase/neon · error

need 1..N positional arguments describing the key, try hex o

Error message

need 1..N positional arguments describing the key, try hex or a log line

What it means

The pageserver_ctl key subcommand builds a Key from 1..N positional arguments. An empty argument list cannot describe a key, so it bails immediately with a hint listing the accepted forms: a hex key, or a pasted log line, or a reltag plus block number.

Source

Thrown at pageserver/ctl/src/key.rs:183

impl From<KeyMaterial> for Key {
    fn from(value: KeyMaterial) -> Self {
        match value {
            KeyMaterial::Hex(key) => key,
            KeyMaterial::String(SpanAttributesFromLogs(rt, blocknum))
            | KeyMaterial::Split(rt, blocknum) => {
                pageserver_api::key::rel_block_to_key(rt, blocknum)
            }
        }
    }
}

impl<S: AsRef<str>> TryFrom<&[S]> for KeyMaterial {
    type Error = anyhow::Error;

    fn try_from(value: &[S]) -> Result<Self, Self::Error> {
        match value {
            [] => anyhow::bail!(
                "need 1..N positional arguments describing the key, try hex or a log line"
            ),
            [one] => {
                let one = one.as_ref();

                let key = Key::from_hex(one).map(KeyMaterial::Hex);

                let attrs = SpanAttributesFromLogs::from_str(one).map(KeyMaterial::String);

                match (key, attrs) {
                    (Ok(key), _) => Ok(key),
                    (_, Ok(s)) => Ok(s),
                    (Err(e1), Err(e2)) => anyhow::bail!(
                        "failed to parse {one:?} as hex or span attributes:\n- {e1:#}\n- {e2:#}"
                    ),
                }
            }
            more => {

View on GitHub (pinned to 8f60b04da4)

Solutions

1. Supply at least one argument: a hex key (as printed by the pageserver), a log line containing rel= and blkno=, or a reltag followed by a block number.
2. Guard scripts with [ -n "$KEY" ] or a default value before invoking the ctl.

Example fix

# before
pageserver_ctl key "$MAYBE_EMPTY"

# after
pageserver_ctl key "000000067F000100010000AC0000000006"

#!/usr/bin/env bash
# require at least one positional argument
[ "$#" -ge 1 ] || { echo "usage: pageserver_ctl key <hex-key | log-line | reltag blocknum>" >&2; exit 1; }

When it happens

Trigger: Invoking the key subcommand with zero positional arguments.

Common situations: An unset shell variable that expands to nothing ($KEY with KEY empty); scripts that pass an optional argument unconditionally; quoting mistakes that swallow the argument.

Related errors

• unsupported linekind: {s}
• failed to parse {one:?} as hex or span attributes: - {e1:#}
• found no RelTag in arguments
• found no blocknum in arguments
• cannot find 'rel='

AI-assisted analysis of neondatabase/neon@8f60b04da4 (2026-08-16). Data as JSON: /api/errors/02b5e63c9eee4e1e. Report an issue: GitHub.