What causes "usage: collab >" in zed-industries/zed?

Use one of the accepted modes for this build: collab serve api, collab serve collab, or collab serve all

usage: collab <version | serve <api|collab|all>>

Error message

usage: collab <version | serve <api|collab|all>>

What it means

Returned by the collab binary's argument parser when the first argument is 'serve' but the second argument is missing or none of api|collab|all. This variant of the usage string is emitted before the service mode router is built, so nothing starts. It is pure command-line misuse, not a runtime failure.

Source

Thrown at crates/collab/src/main.rs:52

    if let Err(error) = env::load_dotenv() {
        eprintln!(
            "error loading .env.toml (this is expected in production): {}",
            error
        );
    }

    let mut args = args().skip(1);
    match args.next().as_deref() {
        Some("version") => {
            println!("collab v{} ({})", VERSION, REVISION.unwrap_or("unknown"));
        }
        Some("serve") => {
            let mode = match args.next().as_deref() {
                Some("collab") => ServiceMode::Collab,
                Some("api") => ServiceMode::Api,
                Some("all") => ServiceMode::All,
                _ => {
                    return Err(anyhow!("usage: collab <version | serve <api|collab|all>>"))?;
                }
            };

            let config = envy::from_env::<Config>().expect("error loading config");
            init_tracing(&config);
            init_panic_hook();

            let mut app = Router::new()
                .route("/", get(handle_root))
                .route("/healthz", get(handle_liveness_probe))
                .layer(Extension(mode));

            let listener = TcpListener::bind(format!("0.0.0.0:{}", config.http_port))
                .expect("failed to bind TCP listener");

            let mut on_shutdown = None;

            if mode.is_collab() || mode.is_api() {

View on GitHub (pinned to bc538def45)

Solutions

Use one of the accepted modes for this build: collab serve api, collab serve collab, or collab serve all
Check collab version to confirm which modes this build supports
Fix the entrypoint/script so the mode argument is always present and quoted

Example fix

# before
collab serve

# after
collab serve all

Defensive patterns

Strategy: validation

Validate before calling

# Validate the serve mode before launching.
MODE="${1:?usage: collab serve <api|collab|all>}"
case "$MODE" in api|collab|all) ;; *) echo "invalid mode: $MODE" >&2; exit 2 ;; esac
exec collab serve "$MODE"

Prevention

Pin the collab binary version and script arguments together in deployment config
Fail fast in entrypoint scripts with an explicit usage check before exec
Run 'collab version' in CI to assert the expected subcommand set

When it happens

Trigger: Running 'collab serve' with no mode; 'collab serve web', 'collab serve llm' on an older build where llm is not accepted; scripts or container entrypoints that pass an empty or misspelled mode argument.

Common situations: Deployments copying docs from a newer/older zed version whose accepted modes differ (see the sibling usage string that does include llm); CI scripts with unquoted variables producing 'serve ' with no mode; typos in systemd/Docker command lines.

Related errors

AI-assisted analysis of zed-industries/zed@bc538def45 (2026-08-16). Data as JSON: /api/errors/575130ff8f12b5a2. Report an issue: GitHub.