withastro/astro · error · Error

Process exited with code

Error message

Process exited with code ${exitCode}

What it means

`shell()` in @astrojs/upgrade throws when a spawned command exits with a non-zero code. The message prefers the captured stderr (then stdout) of the child, so the error text you see is usually the underlying package-manager output (e.g. `npm ERR! ...`); the literal "Process exited with code N" appears only when the command produced no output at all.

Solutions

  1. Read the embedded npm/pnpm error in the message — it names the conflicting packages
  2. Reproduce manually with the same command (e.g. `npm install astro@latest`) to see the full output
  3. Fix the reported peer conflict by upgrading the conflicting package too, or pin compatible versions
  4. If the lockfile is the problem, regenerate it (delete lockfile + node_modules) and retry
Defensive patterns

Strategy: try-catch

Try / catch

try {
  await runUpgrade();
} catch (e) {
  if (e instanceof Error && /npm ERR!|ERESOLVE|process exited with code/i.test(e.message)) {
    // run the same install manually to see full output and fix the conflict
  }
  throw e;
}

Prevention

When it happens

Trigger: `astro upgrade` runs `npm/pnpm/yarn/bun install` or `update` under the hood and it fails: ERESOLVE peer-dependency conflicts, missing registry auth, invalid package.json, lockfile out of sync, or the package manager binary itself erroring.

Common situations: Peer-dependency conflicts between the new Astro version and other deps (most common); corrupted lockfiles after switching package managers; private registry credentials expired mid-run; monorepo hoisting conflicts.

Related errors

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

Appendix: source

Thrown at packages/upgrade/src/shell.ts:75

			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 || stdout || `Process exited with code ${exitCode}`);
	}
	return { stdout, stderr, exitCode };
}

View on GitHub (pinned to 52e6c34790)