{"record":{"id":"720921a0664e3855","repo":"withastro/astro","slug":"unable-to-download-template-tmpl","errorCode":null,"errorMessage":"Unable to download template ${tmpl}","messagePattern":"Unable to download template (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/create-astro/src/actions/template.ts","lineNumber":211,"sourceCode":"\t\t\t\tthrow new Error(`Template ${color.reset(tmpl)} ${color.dim('does not exist!')}`);\n\t\t\t}\n\n\t\t\tif (err.message) {\n\t\t\t\terror('error', err.message);\n\t\t\t}\n\t\t\ttry {\n\t\t\t\t// The underlying error is often buried deep in the `cause` property\n\t\t\t\t// This is in a try/catch block in case of weirdnesses in accessing the `cause` property\n\t\t\t\tif ('cause' in err) {\n\t\t\t\t\t// This is probably included in err.message, but we can log it just in case it has extra info\n\t\t\t\t\terror('error', err.cause);\n\t\t\t\t\tif ('cause' in err.cause) {\n\t\t\t\t\t\t// Hopefully the actual fetch error message\n\t\t\t\t\t\terror('error', err.cause?.cause);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} catch {}\n\t\t\tthrow new Error(`Unable to download template ${color.reset(tmpl)}`);\n\t\t}\n\n\t\tif (ctx.ai) {\n\t\t\t// Generate AGENTS.md for AI coding agents, with a CLAUDE.md link\n\t\t\tconst agentsPath = path.resolve(ctx.cwd, 'AGENTS.md');\n\t\t\tconst claudePath = path.resolve(ctx.cwd, 'CLAUDE.md');\n\t\t\tfs.writeFileSync(agentsPath, generateAgentsMd());\n\t\t\ttry {\n\t\t\t\tfs.symlinkSync('AGENTS.md', claudePath);\n\t\t\t} catch {\n\t\t\t\ttry {\n\t\t\t\t\tfs.linkSync(agentsPath, claudePath);\n\t\t\t\t} catch {\n\t\t\t\t\t// Link creation failed; AGENTS.md still exists\n\t\t\t\t}\n\t\t\t}\n\t\t}\n","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/create-astro/src/actions/template.ts#L193-L229","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Check the printed `cause` chain above this error for the real underlying failure (fetch error, EACCES, etc.).","Retry on a stable network connection; if rate-limited, wait or authenticate.","If filesystem-related, ensure the target directory is writable and not already populated.","As a fallback, clone the template directly: `git clone https://github.com/withastro/astro` and copy the example folder."],"exampleFix":"# before — failing\nnpm create astro@latest -- --template minimal\n\n# after — diagnose then retry\ngit clone --depth=1 https://github.com/withastro/astro /tmp/astro && cp -r /tmp/astro/examples/minimal ./my-site","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"async function scaffoldWithRetry(template, retries = 2) {\n  for (let i = 0; i <= retries; i++) {\n    try { return await createProject({ template }); }\n    catch (e) {\n      if (/Unable to download/.test(e.message) && i < retries) { await new Promise(r => setTimeout(r, 1000 * (i+1))); continue; }\n      throw e;\n    }\n  }\n}","preventionTips":["Check connectivity to raw.githubusercontent.com before scaffolding.","Read the printed `cause` chain to find the real failure.","Keep a local clone of the astro repo as an offline fallback for the examples folder."],"tags":["create-astro","cli","template","network","filesystem"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}