{"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":822,"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":804,"sourceCodeEnd":840,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/3653d2ed498fddbd83b7062aa6bf8970e18635ec/crates/cli/src/subcommands/dev.rs#L804-L840","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run the exact client command manually in the project directory (e.g. `npm run dev`) and fix whatever error it prints","Install client dependencies first: `npm install` (or pnpm/yarn equivalent)","Check the `client` command string in spacetime.json for typos and make sure the script exists in package.json","Verify the required binary (node, npm, pnpm) is on PATH for the terminal running `spacetime dev`","If the client legitimately needs >200ms to fail, reproduce outside `spacetime dev` since the message only mirrors the child's exit code"],"exampleFix":"# before (spacetime.json)\n\"client\": \"npm run devx\"\n# after\n\"client\": \"npm run dev\"\n# and if deps are missing:\nnpm install","handlingStrategy":"validation","validationCode":"# before `spacetime dev`, prove the client command works in the project dir\n(npm run dev --prefix . > /dev/null && echo ok) || echo 'fix client command first'","typeGuard":null,"tryCatchPattern":"match dev_exec.await {\n    Ok(_) => {}\n    Err(e) if e.to_string().contains(\"failed immediately\") => {\n        // child's exit: re-run the client command manually for the real stderr\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Run `npm install` (or equivalent) before `spacetime dev` in fresh checkouts","Keep the spacetime.json client command minimal and test it standalone first","Verify node/npm/pnpm are on PATH in the same terminal you launch dev from"],"tags":["spacetime-dev","child-process","cli","npm","exit-code"],"backgroundTag":"child-process-exit-nonzero","analyzedSha":"3653d2ed498fddbd83b7062aa6bf8970e18635ec","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}