What causes "npmFetch failed: fetching ${tarball} - ${res.status}" in parcel-bundler/parcel?

Retry — most tarball fetch failures are transient CDN errors.

parcel-bundler/parcel · error · Error

npmFetch failed: fetching ${tarball} - ${res.status}

Error message

npmFetch failed: fetching ${tarball} - ${res.status}

What it means

Thrown by `SimplePackageInstaller._npmFetch` when the HTTP GET against a package's tarball URL (from `dist.tarball`) returns a non-2xx status. Resolution succeeded but the actual artifact download failed. The tarball URL and status are appended.

Source

Thrown at packages/dev/repl/SimplePackageInstaller/index.js:110

        `${name}@${version}: only npm semver dependencies are currently supported.`,
      );
    }
    this.cache.resolve.set(
      `${name}@${version}`,
      data.versions[resolvedVersion],
    );
    return data.versions[resolvedVersion];
  }

  async _npmFetch(tarball: string): Promise<Map<string, Uint8Array>> {
    const cacheEntry = this.cache.fetch.get(tarball);
    if (cacheEntry) {
      return cacheEntry;
    }

    const res = await fetch(tarball);
    if (!res.ok) {
      throw new Error(`npmFetch failed: fetching ${tarball} - ${res.status}`);
    }

    let result;
    if (!res.arrayBuffer) {
      // node
      var bufs = [];
      res.body.on('data', function (d) {
        bufs.push(d);
      });

      const buffer = await new Promise(resolve =>
        res.body.on('end', () => {
          resolve(Buffer.concat(bufs));
        }),
      );

      result = new ArrayBuffer(buffer.length);
      var view = new Uint8Array(result);

View on GitHub (pinned to 59484858a1)

Solutions

Retry — most tarball fetch failures are transient CDN errors.
Check the status code in the message: 404 → the version was removed, re-resolve for a current one.
Verify network access to the tarball host shown in the message.
If reproducible, report with the exact tarball URL and status.

Defensive patterns

Strategy: retry

Validate before calling

async function tarballOk(url) {
  const r = await fetch(url, { method: 'HEAD' });
  return r.ok;
}

Try / catch

try { await installer._npmFetch(tarball); }
catch (e) {
  if (/npmFetch failed: .* - (429|5\d\d)/.test(e.message)) { await backoffRetry(() => installer._npmFetch(tarball)); }
  else throw e;
}

Prevention

Retry transient CDN errors with backoff.
Cache successful fetches (the installer already does — reuse the instance).
On repeated 404, re-resolve the version.

When it happens

Trigger: Tarball URL is stale/unpublished (404); CDN rate-limit (429); transient CDN error (5xx); mirrored/private registry where the tarball host is unreachable; integrity/unpublish happened between resolve and fetch.

Common situations: Package was unpublished or version yanked mid-session; CDN outage; corporate proxy blocks the tarball CDN host; very large package timing out at the edge.

Related errors

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/0abf57827e46e723. Report an issue: GitHub.