vercel/next.js · error

Failed to download: ${url}

Error message

Failed to download: ${url}

What it means

create-next-app's example downloader (`downloadTarStream`) throws when `fetch(url)` returns a response with no body (`res.body` is null/undefined). This happens before the tar extraction pipeline, meaning the GitHub codeload URL returned a non-streaming or empty response. The error includes the URL so the user can see which fetch failed.

Source

Thrown at packages/create-next-app/helpers/examples.ts:93

export function existsInRepo(nameOrUrl: string): Promise<boolean> {
  try {
    const url = new URL(nameOrUrl)
    return isUrlOk(url.href)
  } catch {
    return isUrlOk(
      `https://api.github.com/repos/vercel/next.js/contents/examples/${encodeURIComponent(
        nameOrUrl
      )}`
    )
  }
}

async function downloadTarStream(url: string) {
  const res = await fetch(url)

  if (!res.body) {
    throw new Error(`Failed to download: ${url}`)
  }

  return Readable.fromWeb(res.body as import('stream/web').ReadableStream)
}

export async function downloadAndExtractRepo(
  root: string,
  { username, name, branch, filePath }: RepoInfo
) {
  let rootPath: string | null = null
  await pipeline(
    await downloadTarStream(
      `https://codeload.github.com/${username}/${name}/tar.gz/${branch}`
    ),
    x({
      cwd: root,
      strip: filePath ? filePath.split('/').length + 1 : 1,
      filter: (p: string) => {

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Check the inlined URL in a browser/curl — if it 404s, fix the example name or repo/branch.
2. Verify network egress to codeload.github.com (proxy, firewall, VPN).
3. Retry during a GitHub outage; check https://www.githubstatus.com.
4. If behind a proxy, set HTTPS_PROXY and ensure it streams large tarballs correctly.

Example fix

# verify the failing URL
curl -L -o /tmp/t.tar.gz 'https://codeload.github.com/vercel/next.js/tar.gz/canary'
# if it 404s, use the correct branch/example name
npx create-next-app --example with-typescript my-app

// Pre-check the URL is reachable before streaming the tarball.
import { isUrlOk } from './examples'
if (!(await isUrlOk(url.href))) {
  throw new Error(`Example URL not reachable: ${url}`)
}

function isCodeloadUrl(u: string): boolean {
  try { return new URL(u).hostname === 'codeload.github.com' } catch { return false }
}

async function safeDownload(url: string, retries = 2) {
  for (let i = 0; i <= retries; i++) {
    try {
      const res = await fetch(url)
      if (res.body) return Readable.fromWeb(res.body)
    } catch (e) { /* last iteration rethrows */ if (i === retries) throw e }
  }
  throw new Error(`Failed to download: ${url}`)
}

When it happens

Trigger: Running `create-next-app --example <name>` (or a custom repo URL) when the codeload.github.com tarball endpoint returns an empty body — e.g. a 404/500 served with no body, a redirected URL that lost the stream, or a network/proxy that stripped the body.

Common situations: Typo in the example name (resolves to a missing repo/branch); GitHub outage returning error pages without a body; corporate proxy/firewall that buffers or drops the stream; offline/air-gapped environment.

Related errors

• This is an internal example for testing the CLI.
• Failed to fetch ${url}
• [${label}] warmup: all ${batchSize} requests failed — server
• Failed to fetch ${url}, too many retries
• `src` and `dest` are required

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/3515db9a1912a997. Report an issue: GitHub.