clockworklabs/SpacetimeDB · error · anyhow::Error

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

Error message

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

What it means

After `spacetime dev` spawns the configured client command (`start_client_process`), it waits ~200ms and calls `try_wait()`. If the child already exited with a non-success status, it bails with the command and its exit code — a fail-fast so the dev loop does not sit watching a dead client. 'unknown' is printed when the process was terminated by a signal (no exit code).

Source

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

        )
        .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 524b4487d9)

Solutions

1. Run the client command manually in another terminal to see its real error output
2. Fix the root cause the exit code indicates: install deps (`npm install`), correct the command, export required env vars
3. Check the command string in `spacetime.json` matches an executable that exists on PATH from the project directory
4. If the client legitimately exits fast (e.g. a one-shot script), reconsider whether it belongs in the dev `client` command

Example fix

# before: "client": "npm run dev" but deps missing
Client command 'npm run dev' failed immediately with exit code: 2
# after
npm install && spacetime dev

# Smoke-test the client command before starting dev
cmd=$(jq -r '.client' spacetime.json)
[ -n "$cmd" ] && sh -lc "$cmd" --dry-run >/dev/null 2>&1 || npm install  # adjust to your stack

// On anyhow error, match the 'failed immediately' prefix, print the client's own stderr/logs, fix deps/env, then restart the dev loop — do not auto-retry in a tight cycle.

When it happens

Trigger: A `client` command in `spacetime.json` that exits immediately: command not found (shell 127), missing runtime (node/python not on PATH), missing deps, config error causing instant exit, or a signal kill within 200ms.

Common situations: `npm run dev` where node_modules is not installed; a client script that exits on missing env vars; wrong command name after package.json rename; port already in use causing immediate crash.

Related errors

• Failed to check client process status: {}
• Unsupported --dotnet-version {version}. Supported values: 8,
• No such saved server configuration: {server} Add a new serve
• No default server configuration. Set an existing server as t
• Server nickname {} already in use: {}://{}

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