What causes "Process exited with code ${exitCode}" in withastro/astro?

Re-run the create command and watch the terminal for which step failed (install vs git vs template fetch).

withastro/astro · error · Error

Process exited with code

Error message

Process exited with code ${exitCode}

What it means

create-astro ships a minimal execa-like helper (packages/create-astro/src/shell.ts) that spawns external commands (npm/pnpm/yarn/bun install, git init, etc.) while scaffolding a project. After the child process closes, any non-zero exit code is fatal; when stderr is empty the helper falls back to this generic 'Process exited with code N' message. So the error means a subprocess failed without emitting any diagnostic output on stderr.

Solutions

Re-run the create command and watch the terminal for which step failed (install vs git vs template fetch).
cd into the generated directory and run the same package-manager install manually (e.g. `npm install`) to get the real error output.
Verify required binaries exist: `git --version` and your package manager `--version` are on PATH.
Check registry connectivity/proxy config (npm config get registry, proxy env vars) if the failing step is dependency installation.
Free disk space / disable antivirus scans for the project folder if installs die silently on Windows.

Defensive patterns

Strategy: try-catch

Validate before calling

// Before invoking create-astro programmatically, verify the binaries it shells out to exist:
import { which } from 'shelljs'; // or: spawnSync('git', ['--version'])
for (const bin of ['git', 'npm']) {
  if (!which(bin)) console.warn(`${bin} not found on PATH — scaffolding steps may fail`);
}

Try / catch

import { shell } from 'create-astro/shell'; // internal usage
try {
  await shell('npm', ['install'], { cwd: projectDir, timeout: 120_000 });
} catch (e) {
  // message is either stderr or 'Process exited with code N' — surface both to the user
  throw new Error(`Dependency installation failed: ${e instanceof Error ? e.message : e}`);
}

Prevention

Pre-install and verify git plus your package manager on PATH before scaffolding.
Run create-astro in an environment with registry access (check proxy/VPN).
Pass a generous timeout when invoking shell programmatically so slow installs exit as 'Timeout' rather than dying silently.

When it happens

Trigger: Running `npm create astro@latest` (or invoking create-astro programmatically) where a spawned step fails silently: package-manager install exiting non-zero with empty stderr, `git init`/`git clone` failing because git is not installed, or a command being killed by a signal/timeout path that leaves exitCode set and stderr blank.

Common situations: Broken registry/proxy or corporate network blocking npm during dependency install; git missing from PATH when a template initializes a repo; disk-full or antivirus interference on Windows; flaky CI networks where the package manager dies without printing anything.

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/97fc78b0c6889a49. Report an issue: GitHub.

Appendix: source

Thrown at packages/create-astro/src/shell.ts:74

			cwd: opts.cwd,
			stdio: opts.stdio,
			timeout: opts.timeout,
		});
		const done = new Promise<void>((resolve, reject) => {
			child.once('error', reject);
			child.once('close', () => resolve());
		});
		[stdout, stderr] = await Promise.all([text(child.stdout), text(child.stderr), done]);
	} catch (e) {
		const message = e instanceof Error ? e.message : stderr || 'Unknown error';
		throw new Error(message);
	}
	const { exitCode } = child;
	if (exitCode === null) {
		throw new Error('Timeout');
	}
	if (exitCode !== 0) {
		throw new Error(stderr || `Process exited with code ${exitCode}`);
	}
	return { stdout, stderr, exitCode };
}

View on GitHub (pinned to 52e6c34790)