{"record":{"id":"d93e57f9a874b686","repo":"payloadcms/payload","slug":"failed-to-download-url","errorCode":null,"errorMessage":"Failed to download: ${url}","messagePattern":"Failed to download: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/create-payload-app/src/lib/download-example.ts","lineNumber":42,"sourceCode":"    debugLog(`Codeload url: ${url}`)\n    debugLog(`Filter: ${filter}`)\n  }\n\n  await pipeline(\n    await downloadTarStream(url),\n    x({\n      cwd: projectDir,\n      filter: (p) => p.includes(filter),\n      strip: 2 + example.name.split('/').length,\n    }),\n  )\n}\n\nasync function downloadTarStream(url: string) {\n  const res = await fetch(url)\n\n  if (!res.body) {\n    throw new Error(`Failed to download: ${url}`)\n  }\n\n  return Readable.from(res.body as unknown as NodeJS.ReadableStream)\n}\n","sourceCodeStart":24,"sourceCodeEnd":47,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/create-payload-app/src/lib/download-example.ts#L24-L47","documentation":"Thrown by downloadTarStream after fetch() resolves against the payloadcms/payload codeload tar.gz URL but res.body is falsy. This guards the stream pipeline (tar extraction) which needs readable bytes. The check does NOT verify res.ok, so HTTP error statuses with a body slip past; only a missing/empty body triggers it.","triggerScenarios":"Running create-payload-app with --example where the GitHub codeload endpoint returns a response with no body (opaque response, redirect to a bodyless 3xx, a corporate proxy stripping bodies, or a non-compliant global fetch shim). Also reachable in runtimes whose fetch returns null body for non-2xx.","commonSituations":"Behind a corporate proxy or firewall that intercepts codeload.github.com; offline/cached CI with a patched fetch; running an old Node version where undici fetch behaves differently; the example's branch/tag (example.url#<ref>) was deleted so codeload returns an empty body.","solutions":["Verify network access to https://codeload.github.com/payloadcms/payload/tar.gz/<branch> (curl -I) and disable/inspect any HTTP proxy.","Re-run with --debug to print the exact codeload URL and confirm the branchOrTag resolved from example.url is correct.","Confirm the referenced branch/tag still exists in the payloadcms/payload repo; switch to a stable tag if it was removed.","Upgrade Node to a version with a compliant global fetch (>=18 with undici) and ensure no polyfill overrides it."],"exampleFix":"// before\nconst res = await fetch(url)\nif (!res.body) {\n  throw new Error(`Failed to download: ${url}`)\n}\n\n// after — also surface HTTP failures clearly\nconst res = await fetch(url)\nif (!res.ok) {\n  throw new Error(`Failed to download (HTTP ${res.status}): ${url}`)\n}\nif (!res.body) {\n  throw new Error(`Failed to download (empty body): ${url}`)\n}","handlingStrategy":"retry","validationCode":"// Pre-flight the codeload URL reachability before invoking create-payload-app\nimport { request } from 'undici'\n\nasync function assertCodeloadReachable(branchOrTag: string) {\n  const url = `https://codeload.github.com/payloadcms/payload/tar.gz/${branchOrTag}`\n  const res = await request(url, { method: 'HEAD' })\n  if (res.statusCode >= 400) {\n    throw new Error(`codeload unreachable for ${branchOrTag}: HTTP ${res.statusCode}`)\n  }\n}\nawait assertCodeloadReachable('latest')","typeGuard":null,"tryCatchPattern":"// Wrap the create-payload-app invocation and retry on transient bodyless responses\nasync function downloadWithRetry(url: string, attempts = 3) {\n  for (let i = 0; i < attempts; i++) {\n    try {\n      const res = await fetch(url)\n      if (res.ok && res.body) return res.body\n      if (i === attempts - 1) throw new Error(`Failed to download: ${url}`)\n    } catch (e) {\n      if (i === attempts - 1) throw e\n    }\n    await new Promise((r) => setTimeout(r, 500 * (i + 1)))\n  }\n}","preventionTips":["Run create-payload-app in an environment with direct access to codeload.github.com.","Use --debug to surface the resolved codeload URL before the failure.","Pin example.url to a stable tag rather than a branch that may be deleted."],"tags":["network","create-payload-app","fetch","cli"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}