withastro/astro · error · Error

Unable to download template ${tmpl}

Error message

Unable to download template ${tmpl}

What it means

Thrown by `create-astro` when a template download fails for any reason other than a 404 (the 404 case is handled separately). This is the catch-all after the inner error's message and `cause` chain have been logged. It signals a network, filesystem, or extraction failure during scaffolding.

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

Solutions

1. Check the printed `cause` chain above this error for the real underlying failure (fetch error, EACCES, etc.).
2. Retry on a stable network connection; if rate-limited, wait or authenticate.
3. If filesystem-related, ensure the target directory is writable and not already populated.
4. As a fallback, clone the template directly: `git clone https://github.com/withastro/astro` and copy the example folder.

Example fix

# before — failing
npm create astro@latest -- --template minimal

# after — diagnose then retry
git clone --depth=1 https://github.com/withastro/astro /tmp/astro && cp -r /tmp/astro/examples/minimal ./my-site

async function scaffoldWithRetry(template, retries = 2) {
  for (let i = 0; i <= retries; i++) {
    try { return await createProject({ template }); }
    catch (e) {
      if (/Unable to download/.test(e.message) && i < retries) { await new Promise(r => setTimeout(r, 1000 * (i+1))); continue; }
      throw e;
    }
  }
}

When it happens

Trigger: The template archive download is interrupted, the GitHub API rate-limits the request, the local filesystem is read-only, or extraction (unzip/tar) fails. The original error message and nested `cause` are printed via `error()` before this generic message is thrown.

Common situations: Offline or behind a corporate proxy that blocks raw.githubusercontent.com. GitHub API rate limit exceeded. Disk full or permission denied writing to the target directory. Corrupt download (interrupted connection).

Related errors

• Template ${tmpl} does not exist!
• Unable to fetch ${integration}. Does the package exist?
• [preview] The output directory ${outDirPath} does not exist.
• Timeout
• Process exited with code ${exitCode}

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