unknown namespace '{namespace}'. Run `openhuman --help` to s

Error message

unknown namespace '{namespace}'. Run `openhuman --help` to see available namespaces.

What it means

Namespace resolution against the controller registry found no match for the first positional token. Per the source comments, a plain CLI invocation has no ambient CoreContext, so runtime DomainSet gating does NOT hide namespaces here — the per-function capability gate fires later instead. This error therefore means the namespace is absent from this binary's compiled registry: a typo, or its cargo feature gate was compiled out (e.g. `flows` off means the `flows` namespace genuinely does not exist). The retained `mcp`/`tui` arms report build facts separately; everything else is a real unknown.

Source

Thrown at src/core/cli.rs:543

    args: &[String],
    grouped: &BTreeMap<String, Vec<ControllerSchema>>,
) -> Result<()> {
    let Some(schemas) = grouped.get(namespace) else {
        // Reachable only when `grouped` really was filtered — i.e. under
        // `run`/`serve`/TUI, which build a `CoreContext`. On a plain CLI
        // invocation there is no ambient context, so nothing is filtered and a
        // gated namespace is still present; the per-function gate below is what
        // fires there. Consult the UNFILTERED registry before reporting a typo:
        // silence reads as a mistyped command and sends the user off debugging
        // their own command line, which is exactly what `docs/specs/kernel.md`
        // §3.3 carves the CLI out of. Same reasoning as the retained `mcp` and
        // `tui` arms above. A namespace that does not exist at all yields `None`
        // and still reports unknown.
        crate::core::cli_capability::ensure_capability_blocking(
            all::sole_capability_for_namespace(namespace),
            &format!("openhuman {namespace}"),
        )?;
        return Err(anyhow::anyhow!(
            "unknown namespace '{namespace}'. Run `openhuman --help` to see available namespaces."
        ));
    };

    if args.is_empty() || is_help(&args[0]) {
        // If there's a domain-specific CLI handler for this namespace, use it as the default.
        if let Some(cli_handler) = all::cli_handler_for_namespace(namespace) {
            return cli_handler(args);
        }
        print_namespace_help(namespace, schemas);
        return Ok(());
    }

    let function = args[0].as_str();

    // Gate BEFORE resolving the schema, not in the not-found arm below.
    //
    // `grouped` comes from `all_controller_schemas()`, which filters through the

View on GitHub (pinned to a221052e0d)

Solutions

Run `openhuman --help` to list the namespaces this binary actually registered
Fix typos/abbreviations (e.g. `flows`, not `flow` or `mem`)
If the namespace is cargo-feature-gated in this build, rebuild with that feature (e.g. `--features flows`)

Example fix

# before
openhuman flow list
# -> unknown namespace 'flow'
# after
openhuman flows list

Defensive patterns

Strategy: validation

Validate before calling

# bash: check the namespace against this binary's own help before dispatch
openhuman --help 2>/dev/null | grep -qw "$NS" \
  || { echo "unknown namespace '$NS' (typo, or feature-gated out of this build)" >&2; exit 2; }
openhuman "$NS" "$@"

Try / catch

if ! out=$(openhuman "$ns" "$fn" 2>&1); then
  case "$out" in
    *"unknown namespace"*) echo "typo or gated build: $ns" >&2 ;;
    *"unknown function"*) echo "check '$openhuman $ns --help'" >&2 ;;
    *) printf '%s\n' "$out" >&2 ;;
  esac
  exit 1
fi

Prevention

Remember CLI namespace lookup is unfiltered by runtime DomainSet — unknown here means typo or compiled-out by a cargo feature, not runtime-disabled
List what this binary actually has with `openhuman --help` before scripting namespaces
Run scripts against the same feature set they were written for (slim vs product builds differ)

When it happens

Trigger: `openhuman flow list` (typo for `flows`); `openhuman flows ...` on a build with the `flows` feature off; `openhuman mem ...` (abbreviated namespace); namespaces renamed between versions.

Common situations: Scripts written against a full product build run on a slim/contrib build; typos and abbreviations; version drift after a namespace rename (RPC namespaces are string literals, not module paths, so renames are possible).

Related errors

AI-assisted analysis of tinyhumansai/openhuman@a221052e0d (2026-08-16). Data as JSON: /api/errors/4a50f96d85215288. Report an issue: GitHub.