withastro/astro · error · Error

Timeout

Error message

Timeout

What it means

The upgrade tool's minimal execa-like `shell()` spawns child processes (package manager install/update commands) with Node's `spawn` `timeout` option. When the timeout fires, Node kills the child with a signal, so `exitCode` is `null`; the wrapper reports that state as "Timeout". It means the spawned command exceeded its allotted time without exiting cleanly.

Solutions

1. Kill stale package-manager processes that may hold locks (`ps aux | grep npm`), then rerun the upgrade
2. Ensure the environment is non-interactive and won't prompt (set `CI=true`, configure registry auth)
3. Pre-warm the package manager cache (`npm cache verify`) or fix registry connectivity, then retry
4. If the timeout is genuinely too short for the install, run the install manually with your package manager and use `astro upgrade` only for the version bumping

try {
  await runUpgrade();
} catch (e) {
  if (e instanceof Error && e.message === 'Timeout') {
    // child install command hung: clear locks/prompts and retry once
  }
}

When it happens

Trigger: A child command (e.g. `npm install` run by `astro upgrade`) hanging: waiting for interactive input in a TTY-less CI shell, a stalled network fetch on a slow registry, a package manager lock wait (concurrent npm process holding package-lock), all exceeding the configured timeout in milliseconds.

Common situations: Running `astro upgrade` in CI where npm prompts for confirmation and blocks; corporate proxies that stall registry requests; a leftover package-manager process holding a lockfile; very large dependency trees on slow disks.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Process exited with code
• Timeout
• Be sure to follow the
• `markdown.remarkPlugins`, `markdown.rehypePlugins`, and…
• maxDuration is set to

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

Appendix: source

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

	try {
		const [resolvedCommand, resolvedFlags] = resolveCommand(command, flags);
		child = spawn(resolvedCommand, resolvedFlags, {
			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)