withastro/astro · error · Error

Process exited with code ${exitCode}

Error message

Process exited with code ${exitCode}

What it means

Thrown by `create-astro`'s `shell()` helper when the spawned child process exits with a non-zero status code. The error message is the captured stderr if non-empty, otherwise the literal exit code. It indicates the underlying command ran to completion but reported failure.

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 d081033d5f)

Solutions

1. Read the captured stderr in the error message — it usually names the failing package or command.
2. Re-run the failing command manually outside create-astro to get full output and iterate.
3. Clear the package manager cache or switch registries if the failure is network/registry related.
4. Pin a known-good Node.js / package manager version if the failure is environment-specific.

Example fix

# before — create-astro exits with 'Process exited with code 1'
npm create astro@latest

# after — run install manually to see full error
cd my-site && npm install 2>&1 | less

try {
  await shell(cmd, flags);
} catch (e) {
  // e.message is stderr or 'Process exited with code N'
  console.error('Command failed:', e.message);
  throw e;
}

When it happens

Trigger: Any `shell()` invocation where the command exits non-zero: a package manager install failing on peer deps, a git command failing on auth, a build step failing. The check is `exitCode !== 0` after the process closes.

Common situations: `npm install` / `pnpm install` failing during scaffolding due to registry errors or peer-dep conflicts. A post-install script crashing. A git operation rejected by credentials. Network blips causing a package fetch failure mid-install.

Related errors

• Timeout
• Template ${tmpl} does not exist!
• Unable to download template ${tmpl}
• Unknown error parsing tsconfig.json or jsconfig.json. Could
• ${integration} does not appear to be a valid package name!

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