withastro/astro · error · Error

Unable to download template ${color.reset(tmpl)}

Error message

Unable to download template ${color.reset(tmpl)}

What it means

The scaffolding step downloads the resolved template via giget (GitHub tarballs). Any non-404 failure — DNS or network errors, proxies blocking github.com/codeload.github.com, GitHub rate limiting, auth failures on private repos — is logged (including the buried cause chain) and rethrown as 'Unable to download template'. The underlying cause printed just above the message usually identifies the real problem.

Source

Thrown at packages/create-astro/src/actions/template.ts:211

				throw new Error(`Template ${color.reset(tmpl)} ${color.dim('does not exist!')}`);
			}

			if (err.message) {
				error('error', err.message);
			}
			try {
				// The underlying error is often buried deep in the `cause` property
				// This is in a try/catch block in case of weirdnesses in accessing the `cause` property
				if ('cause' in err) {
					// This is probably included in err.message, but we can log it just in case it has extra info
					error('error', err.cause);
					if ('cause' in err.cause) {
						// Hopefully the actual fetch error message
						error('error', err.cause?.cause);
					}
				}
			} catch {}
			throw new Error(`Unable to download template ${color.reset(tmpl)}`);
		}

		if (ctx.ai) {
			// Generate AGENTS.md for AI coding agents, with a CLAUDE.md link
			const agentsPath = path.resolve(ctx.cwd, 'AGENTS.md');
			const claudePath = path.resolve(ctx.cwd, 'CLAUDE.md');
			fs.writeFileSync(agentsPath, generateAgentsMd());
			try {
				fs.symlinkSync('AGENTS.md', claudePath);
			} catch {
				try {
					fs.linkSync(agentsPath, claudePath);
				} catch {
					// Link creation failed; AGENTS.md still exists
				}
			}
		}

View on GitHub (pinned to 52e6c34790)

Solutions

1. Retry on a stable network — most of these failures are transient
2. Read the logged error and its cause above the message: 403 means rate limit, DNS/proxy errors mean network config
3. For CI, authenticate GitHub requests (GITHUB_TOKEN) or vendor the template and scaffold from a local path
4. If a proxy is required, ensure HTTPS_PROXY is exported in the environment

for (let attempt = 1; attempt <= 3; attempt++) {
	try {
		await downloadTemplate(templateTarget, { force: true, cwd, dir: '.' });
		break;
	} catch (e) {
		if (String(e?.message).includes('404') || attempt === 3) throw e;
		await new Promise((r) => setTimeout(r, 1000 * attempt)); // transient network/rate limit
	}
}

When it happens

Trigger: Offline or flaky network; corporate proxy blocking codeload.github.com; GitHub rate limits from unauthenticated CI; private repositories without credentials; a --ref that exists but cannot be fetched.

Common situations: CI sandboxes with restricted egress; corporate networks requiring a proxy; ephemeral CI hitting API rate limits; intermittent GitHub availability.

Related errors

• Template ${color.reset(tmpl)} ${color.dim('does not exist!')
• Timeout
• Process exited with code ${exitCode}
• Unable to fetch latest ${packageName} version from the npm r
• Unable to fetch ${integration}. Does the package exist?

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