vercel/turborepo · error · DownloadError

isErrorLike(reason) ? reason.message : String(reason)

Error message

isErrorLike(reason) ? reason.message : String(reason)

What it means

createProject wraps its entire download/extract/inspect phase and rethrows any failure as a DownloadError, carrying the original message (reason.message when error-like, String(reason) otherwise). So this error is a facade: the text you see comes from whatever failed underneath - a fetch error, a GitHub API response, a tar extraction error, or a package.json parse failure.

Solutions

1. Read the inner message - it is the real cause; treat this error as a wrapper, not a diagnosis
2. If the inner text mentions a status code (403/429), handle GitHub rate limiting: wait or authenticate
3. If it is a socket/DNS error, fix network/proxy env (HTTPS_PROXY) and retry
4. If it is a parse error, the downloaded template is corrupt; retry or pick another example
5. Retry transiently: this path has no built-in retry, one attempt then throw

// Cheap connectivity pre-flight before createProject
import { lookup } from "node:dns/promises";
async function networkUp(host = "codeload.github.com"): Promise<boolean> {
  try { await lookup(host); return true; } catch { return false; }
}

import { DownloadError } from "@turbo-utils";

function isDownloadError(err: unknown): err is DownloadError {
  return err instanceof DownloadError;
}

try {
  const { appPath } = await createProject(opts);
} catch (err) {
  if (err instanceof DownloadError) {
    console.error("Template download failed:", err.message); // inner cause is the real diagnosis
    if (/ENOTFOUND|ECONNREFUSED|fetch failed/.test(err.message)) {
      // network issue - guide user to check proxy/offline state
    }
  }
  throw err;
}

When it happens

Trigger: Any exception inside createProject: the repo metadata fetch (GitHub API), the tarball download (see 'Failed to download: <status>'), missing network (ENOTFOUND/ECONNREFUSED), invalid example name, or errors while reading scripts from the extracted package.json. The loader is stopped and the original message is wrapped.

Common situations: Offline or proxied networks during create-turbo, GitHub API rate limits (secondary rate limit JSON responses), DNS failures in CI, or a template whose package.json cannot be read/parsed after extraction.

Related errors

• Failed to download
• `git ` failed
• Git download failed: Falling back to downloading the…
• Blocked symlink
• Directory path contains potentially unsafe characters

AI-assisted analysis of vercel/turborepo@f9245100cf (2026-08-17). Data as JSON: /api/errors/7764cdb96b993382. Report an issue: GitHub.

Appendix: source

Thrown at packages/turbo-utils/src/create-project.ts:214

      } catch {
        // ignore
      }

      if (packageJsonContent) {
        // read the scripts from the package.json
        availableScripts.push(...Object.keys(packageJsonContent.scripts || {}));
      }
    }

    let cdPath: string = appPath;
    if (path.join(originalDirectory, appName) === appPath) {
      cdPath = appName;
    }

    return { cdPath, hasPackageJson, availableScripts, repoInfo };
  } catch (reason) {
    loader.stop();
    throw new DownloadError(
      isErrorLike(reason) ? reason.message : String(reason)
    );
  }
}

View on GitHub (pinned to f9245100cf)