{"record":{"id":"dda3297b6aad6b15","repo":"withastro/astro","slug":"unable-to-download-template-color-reset-tmpl","errorCode":null,"errorMessage":"Unable to download template ${color.reset(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/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/create-astro/src/actions/template.ts#L193-L229","documentation":"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.","triggerScenarios":"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.","commonSituations":"CI sandboxes with restricted egress; corporate networks requiring a proxy; ephemeral CI hitting API rate limits; intermittent GitHub availability.","solutions":["Retry on a stable network — most of these failures are transient","Read the logged error and its cause above the message: 403 means rate limit, DNS/proxy errors mean network config","For CI, authenticate GitHub requests (GITHUB_TOKEN) or vendor the template and scaffold from a local path","If a proxy is required, ensure HTTPS_PROXY is exported in the environment"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"for (let attempt = 1; attempt <= 3; attempt++) {\n\ttry {\n\t\tawait downloadTemplate(templateTarget, { force: true, cwd, dir: '.' });\n\t\tbreak;\n\t} catch (e) {\n\t\tif (String(e?.message).includes('404') || attempt === 3) throw e;\n\t\tawait new Promise((r) => setTimeout(r, 1000 * attempt)); // transient network/rate limit\n\t}\n}","preventionTips":["Ensure network access to github.com and codeload.github.com (check proxies and HTTPS_PROXY)","Set GITHUB_TOKEN in CI to avoid unauthenticated rate limits when scaffolding","Keep a local copy of your template as a fallback for air-gapped or flaky environments"],"tags":["create-astro","cli","template","network","download"],"backgroundTag":"template-download-failed","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}