{"record":{"id":"cfbbe855a30f3c4f","repo":"clockworklabs/SpacetimeDB","slug":"client-command-failed-immediately-with-exit-c","errorCode":null,"errorMessage":"Client command '{}' failed immediately with exit code: {}","messagePattern":"Client command '(.+?)' failed immediately with exit code: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/cli/src/subcommands/dev.rs","lineNumber":799,"sourceCode":"        )\n        .await?;\n        log_handles.push(handle);\n    }\n\n    // Start the client development server if configured\n    let server_opt_client = publish_configs\n        .first()\n        .and_then(|c| c.get_one::<String>(\"server\").ok().flatten());\n    let server_for_client = server_opt_client.as_deref().unwrap_or(resolved_server);\n    let server_host_url = config.get_host_url(Some(server_for_client))?;\n    let mut client_handle = if let Some(ref cmd) = client_command {\n        let mut child = start_client_process(cmd, &project_dir, db_name_for_client, &server_host_url)?;\n\n        // Give the process a moment to fail fast (e.g., command not found, missing deps)\n        sleep(Duration::from_millis(200)).await;\n        match child.try_wait() {\n            Ok(Some(status)) if !status.success() => {\n                anyhow::bail!(\n                    \"Client command '{}' failed immediately with exit code: {}\",\n                    cmd,\n                    status\n                        .code()\n                        .map(|c| c.to_string())\n                        .unwrap_or_else(|| \"unknown\".to_string())\n                );\n            }\n            Err(e) => {\n                anyhow::bail!(\"Failed to check client process status: {}\", e);\n            }\n            _ => {} // Still running or exited successfully (unusual but ok)\n        }\n        Some(child)\n    } else {\n        None\n    };\n","sourceCodeStart":781,"sourceCodeEnd":817,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/cli/src/subcommands/dev.rs#L781-L817","documentation":"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).","triggerScenarios":"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.","commonSituations":"`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.","solutions":["Run the client command manually in another terminal to see its real error output","Fix the root cause the exit code indicates: install deps (`npm install`), correct the command, export required env vars","Check the command string in `spacetime.json` matches an executable that exists on PATH from the project directory","If the client legitimately exits fast (e.g. a one-shot script), reconsider whether it belongs in the dev `client` command"],"exampleFix":"# before: \"client\": \"npm run dev\" but deps missing\nClient command 'npm run dev' failed immediately with exit code: 2\n# after\nnpm install && spacetime dev","handlingStrategy":"validation","validationCode":"# Smoke-test the client command before starting dev\ncmd=$(jq -r '.client' spacetime.json)\n[ -n \"$cmd\" ] && sh -lc \"$cmd\" --dry-run >/dev/null 2>&1 || npm install  # adjust to your stack","typeGuard":null,"tryCatchPattern":"// 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.","preventionTips":["Install client deps before `spacetime dev`","Pin interpreters/commands that exist on PATH; test the command by hand first"],"tags":["cli","subprocess","client-command","spacetimedb"],"backgroundTag":"child-process-exit-nonzero","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}