unionlabs/union · error

unknown IBC spec `{ibc_spec_id}`

Error message

unknown IBC spec `{ibc_spec_id}`

What it means

For `voyager rpc client-state --decode`, the CLI must build the on-chain storage key for the client state itself, using a local map `ibc_handlers` keyed by IBC spec ID. That map is hardcoded at voyager/src/main.rs:422-427 to exactly two entries: `IbcClassic::ID` ("ibc-classic") and `IbcUnion::ID` ("ibc-union"). Passing any other `--ibc-spec-id` makes `HashMap::get` return `None`, and `.context(anyhow!(...))` attaches this message.

Source

Thrown at voyager/src/main.rs:492

                        .await?;

                    print_json(&client_info);
                }
                RpcCmd::ClientState {
                    on,
                    client_id,
                    ibc_spec_id,
                    height,
                    decode,
                } => {
                    let ibc_state = voyager_client
                        .query_ibc_state(
                            on.clone(),
                            ibc_spec_id.clone(),
                            height,
                            (ibc_handlers
                                .get(&ibc_spec_id)
                                .context(anyhow!("unknown IBC spec `{ibc_spec_id}`"))?
                                .client_state_path)(client_id.clone())?,
                        )
                        .await?;

                    match (ibc_state.state, decode) {
                        (Some(state), true) => {
                            let client_info = voyager_client
                                .client_info(on, ibc_spec_id.clone(), client_id)
                                .await?
                                .ok_or(anyhow!("client info not found"))?;

                            let decoded = voyager_client
                                .decode_client_state(
                                    client_info.client_type,
                                    client_info.ibc_interface,
                                    ibc_spec_id,
                                    serde_json::from_value(state)
                                        .expect("serialization is infallible; qed;"),

View on GitHub (pinned to 031785bb6d)

Solutions

1. Use one of the two supported spec IDs: `ibc-classic` (ICS-07 tendermint-style clients) or `ibc-union` (Union's cometbft-client/ics08-wasm style paths).
2. Check for typos in the flag value; the IDs are kebab-case and case-sensitive.
3. If you need a spec beyond the two built-ins, the CLI must be rebuilt from a tree where your spec is added to the `ibc_handlers` map in voyager/src/main.rs:422 (e.g. `(MySpec::ID, IbcSpecHandler::new::<MySpec>())`).
4. If you expected the running server's registered handlers to apply, verify CLI/server versions match — the map is local to the CLI, not fetched from the server.

Example fix

# before
voyager rpc client-state --on cosmos-hub --client-id 07-tendermint-0 --ibc-spec-id tendermint --decode
# error: unknown IBC spec `tendermint`

# after
voyager rpc client-state --on cosmos-hub --client-id 07-tendermint-0 --ibc-spec-id ibc-classic --decode

case "$IBC_SPEC_ID" in ibc-classic|ibc-union) ;; *) echo "unsupported spec: $IBC_SPEC_ID" >&2; exit 2;; esac

fn is_known_ibc_spec(id: &str) -> bool {
    matches!(id, "ibc-classic" | "ibc-union")
}

When it happens

Trigger: Running `voyager rpc client-state --on <chain> --client-id <id> --ibc-spec-id <spec> --decode` with a spec ID other than `ibc-classic` or `ibc-union` (e.g. `ibc-grandpa`, a chain-specific custom spec, or a typo like `ibc_classic`). Note the raw query without `--decode` also needs the handler for the path, so any spec outside the two built-ins fails here.

Common situations: Adding support for a new/custom IBC spec handler on the server side (via `register_ibc_spec_handler`) while the CLI build in use predates it; typo'd spec IDs in scripts; version skew between the CLI and the voyager server that registered extra spec handler plugins.

Related errors

• client info not found
• config file must be specified
• plugin not found
• no database set in config, queue commands require the `pg-qu
• not implemented

AI-assisted analysis of unionlabs/union@031785bb6d (2026-08-16). Data as JSON: /api/errors/b0ed27e1dae116f6. Report an issue: GitHub.