clockworklabs/SpacetimeDB · error · anyhow::Error

Client command ' ' failed immediately with exit code

Error message

Client command '{}' failed immediately with exit code: {}

What it means

Thrown by `spacetime dev` after it spawns the client command from your spacetime.json (`client` field, run via `sh -c` on Unix / `cmd /C` on Windows, in the project dir with SPACETIMEDB_HOST and SPACETIMEDB_DB_NAME set). The CLI waits 200ms and calls try_wait(); if the child already exited with a non-zero status it aborts the whole dev loop. The child's own stderr normally prints just above this message, so read it to find the real cause.

Solutions

1. Run the exact client command manually in the project directory (e.g. `npm run dev`) and fix whatever error it prints
2. Install client dependencies first: `npm install` (or pnpm/yarn equivalent)
3. Check the `client` command string in spacetime.json for typos and make sure the script exists in package.json
4. Verify the required binary (node, npm, pnpm) is on PATH for the terminal running `spacetime dev`
5. If the client legitimately needs >200ms to fail, reproduce outside `spacetime dev` since the message only mirrors the child's exit code

Example fix

# before (spacetime.json)
"client": "npm run devx"
# after
"client": "npm run dev"
# and if deps are missing:
npm install

# before `spacetime dev`, prove the client command works in the project dir
(npm run dev --prefix . > /dev/null && echo ok) || echo 'fix client command first'

match dev_exec.await {
    Ok(_) => {}
    Err(e) if e.to_string().contains("failed immediately") => {
        // child's exit: re-run the client command manually for the real stderr
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: A `client` command that dies within 200ms: command not found (exit 127), `npm run dev` without node_modules installed, a misspelled script name in package.json, a compile error in a build step, or a command that depends on a binary not on PATH in the shell `spacetime dev` inherits.

Common situations: Fresh clone of a project where you ran `spacetime dev` before `npm install`; package.json script renamed; node/npx/pnpm not on PATH in CI or a fresh terminal; Windows users pointing at a .cmd script without the right shell syntax.

Related errors

• Failed to check client process status
• Aborted.
• Aborted.
• Aborting because major version upgrade was not accepted.
• Cannot continue without a module path.

AI-assisted analysis of clockworklabs/SpacetimeDB@3653d2ed49 (2026-08-20). Data as JSON: /api/errors/cfbbe855a30f3c4f. Report an issue: GitHub.

Appendix: source

Thrown at crates/cli/src/subcommands/dev.rs:822

        )
        .await?;
        log_handles.push(handle);
    }

    // Start the client development server if configured
    let server_opt_client = publish_configs
        .first()
        .and_then(|c| c.get_one::<String>("server").ok().flatten());
    let server_for_client = server_opt_client.as_deref().unwrap_or(resolved_server);
    let server_host_url = config.get_host_url(Some(server_for_client))?;
    let mut client_handle = if let Some(ref cmd) = client_command {
        let mut child = start_client_process(cmd, &project_dir, db_name_for_client, &server_host_url)?;

        // Give the process a moment to fail fast (e.g., command not found, missing deps)
        sleep(Duration::from_millis(200)).await;
        match child.try_wait() {
            Ok(Some(status)) if !status.success() => {
                anyhow::bail!(
                    "Client command '{}' failed immediately with exit code: {}",
                    cmd,
                    status
                        .code()
                        .map(|c| c.to_string())
                        .unwrap_or_else(|| "unknown".to_string())
                );
            }
            Err(e) => {
                anyhow::bail!("Failed to check client process status: {}", e);
            }
            _ => {} // Still running or exited successfully (unusual but ok)
        }
        Some(child)
    } else {
        None
    };

View on GitHub (pinned to 3653d2ed49)