tinyhumansai/openhuman · error

unknown run arg: {other}

Error message

unknown run arg: {other}

What it means

`openhuman run` accepts an exact set of tokens — `--port <u16>`, `--host <addr>`, `--jsonrpc-only`, `--headless-api`, `-v`/`--verbose`, `-h`/`--help` — matched by exact string. Anything else, including equals-joined forms and typos, falls to the catch-all arm and is reported verbatim. The strictness is deliberate: guessing flags would misconfigure a long-running server.

Source

Thrown at src/core/cli.rs:418

                i += 1;
            }
            "-h" | "--help" => {
                println!("Usage: openhuman run [--host <addr>] [--port <u16>] [--jsonrpc-only|--headless-api] [-v|--verbose]");
                println!();
                println!(
                    "  --host <addr>    Bind address (default: 127.0.0.1 or OPENHUMAN_CORE_HOST)"
                );
                println!(
                    "  --port <u16>     Listen address port (default: 7788 or OPENHUMAN_CORE_PORT)"
                );
                println!("  --jsonrpc-only   HTTP JSON-RPC only; disable Socket.IO");
                println!("  --headless-api   HTTP JSON-RPC only; disable all background services");
                println!("  -v, --verbose    Shorthand for RUST_LOG=debug when RUST_LOG is unset");
                println!();
                println!("Logging: set RUST_LOG (e.g. RUST_LOG=debug openhuman run). Default level is info.");
                return Ok(());
            }
            other => return Err(anyhow::anyhow!("unknown run arg: {other}")),
        }
    }

    crate::core::logging::init_for_cli_run(verbose, log_scope);

    // Initialize the Tokio multi-threaded runtime.
    //
    // A single agent turn is a very large async state machine (system prompt +
    // hundreds of tool specs + the nested provider/tool loop), and delegating
    // to a sub-agent runs another full turn one level down. Even with the inner
    // sub-agent future boxed (`subagent_runner::ops`), that nesting overflows
    // tokio's default 2 MiB worker-thread stack and aborts the whole process
    // (SIGABRT: "thread 'tokio-rt-worker' has overflowed its stack"), taking
    // the JSON-RPC server down mid-request. Give workers a roomier stack.
    let rt = tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .thread_stack_size(crate::core::runtime::AGENT_WORKER_STACK_BYTES)
        .max_blocking_threads(crate::core::runtime::MAX_BLOCKING_THREADS)

View on GitHub (pinned to a221052e0d)

Solutions

1. Run `openhuman run --help` and copy the exact flags listed
2. Use the space-separated form (`--port 7788`), not `--port=7788`
3. Check spelling of the boolean flags: exactly `--jsonrpc-only`, `--headless-api`, `-v`/`--verbose`

Example fix

# before
openhuman run --port=7788 --jsonrpc-only
# after
openhuman run --port 7788 --jsonrpc-only

# bash: construct run args from a whitelist instead of forwarding raw user input
valid_flags=(--jsonrpc-only --headless-api -v --verbose)
args=(run)
for a in "$@"; do
  case "$a" in --port|--host) ;; # handled with their values below
    "${valid_flags[@]}") args+=("$a") ;;
    *) echo "unsupported run flag: $a" >&2; exit 2 ;;
  esac
done
openhuman "${args[@]}"

When it happens

Trigger: `openhuman run --port=7788` (equals form unsupported); `--jsonrpc_only` (underscore typo); `--headless` (shortened guess); stray positional arguments after `run`.

Common situations: Flag conventions carried over from other CLIs that accept `key=value`; typos; renamed flags across versions; leftover positional text from script templating.

Related errors

• missing value for --port
• invalid --port: {e}
• missing value for --host
• audio blob is empty
• voice_not_compiled

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