pnpm/pnpm · error · PnpmError

INVALID_TARBALL_INTEGRITY

INVALID_TARBALL_INTEGRITY

Error message

Tarball "${dist.tarball}" has invalid shasum specified in its metadata: ${dist.shasum}

What it means

When registry metadata has no `dist.integrity` SRI field, pnpm reconstructs one from `dist.shasum` with ssri.fromHex. If the shasum is not parseable hex (wrong length, non-hex characters, or mangled metadata), the integrity value cannot be built and pnpm rejects the tarball record rather than installing something with an unusable checksum. The message names the offending tarball URL and shasum so you can trace which registry served it.

Source

Thrown at pnpm11/resolving/npm-resolver/src/index.ts:1275

    code: MINIMUM_RELEASE_AGE_VIOLATION_CODE,
    reason: `was published at ${new Date(ts).toISOString()}, within the minimumReleaseAge cutoff (${args.publishedBy.toISOString()})`,
  }
}

function getIntegrity (dist: {
  integrity?: string
  shasum: string
  tarball: string
}): string | undefined {
  if (dist.integrity) {
    return dist.integrity
  }
  if (!dist.shasum) {
    return undefined
  }
  const integrity = ssri.fromHex(dist.shasum, 'sha1')
  if (!integrity) {
    throw new PnpmError('INVALID_TARBALL_INTEGRITY', `Tarball "${dist.tarball}" has invalid shasum specified in its metadata: ${dist.shasum}`)
  }
  return integrity.toString()
}

/**
 * Construct the LRU `PackageMetaCache` instance the resolver uses by
 * default. Exported so the install layer can build one cache and hand
 * the same reference to both the resolver and the verifier — the
 * verifier's fast path reads from it when the resolver has already
 * fetched a packument during the same install.
 */
export function createDefaultPackageMetaCache (): PackageMetaCache {
  return new LRUCache<string, PackageMeta>({
    max: 10000,
    ttl: 120 * 1000, // 2 minutes
  })
}

View on GitHub (pinned to 6261b7f388)

Solutions

1. Identify the source from the tarball URL in the message — the host tells you which registry/mirror served the bad metadata
2. Fix the publishing/proxy side so dist.shasum is the 40-char hex sha1 of the tarball, or emit a proper dist.integrity SRI string
3. Clear the cached packument so pnpm refetches corrected metadata: delete the package's entry under <cacheDir>/metadata (then reinstall)
4. If the package exists on npmjs.org, install that dependency from the canonical registry to bypass the broken mirror

Example fix

// before — packument served by the broken mirror
"dist": { "tarball": "https://npm.corp/foo/-/foo-1.0.0.tgz", "shasum": "cafe0xyz" }

// after — valid 40-char hex sha1 (or add dist.integrity SRI)
"dist": { "tarball": "https://npm.corp/foo/-/foo-1.0.0.tgz", "shasum": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" }

const HEX40 = /^[0-9a-f]{40}$/i
export function assertDistIntegrityUsable (dist: { integrity?: string, shasum?: string, tarball: string }) {
  if (dist.integrity) return
  if (!dist.shasum) return // undefined integrity is allowed by the resolver
  if (!HEX40.test(dist.shasum)) {
    throw new Error(`Registry ${new URL(dist.tarball).host} serves malformed shasum "${dist.shasum}" for ${dist.tarball}`)
  }
}
// run over packuments coming from private registries/proxies in your smoke tests

function isInvalidTarballIntegrity (err: unknown): err is Error & { code: 'ERR_PNPM_INVALID_TARBALL_INTEGRITY' } {
  return typeof err === 'object' && err !== null &&
    (err as { code?: string }).code === 'ERR_PNPM_INVALID_TARBALL_INTEGRITY'
}

try {
  await resolveNpm(wantedDependency, opts)
} catch (err) {
  if (isInvalidTarballIntegrity(err)) {
    // err.message contains the tarball URL and bad shasum — report which registry is broken,
    // clear the packument cache for that package, then retry from the canonical registry
    await clearMetadataCache(spec.name)
    return resolveNpm(wantedDependency, { ...opts, registry: 'https://registry.npmjs.org/' })
  }
  throw err
}

When it happens

Trigger: getIntegrity receives a dist object where integrity is absent and shasum is malformed — typical of private registries/proxies that rewrite packuments (Verdaccio/Nexus plugins), hand-rolled registries, or a mirror bug — e.g. shasum truncated or base64 instead of hex.

Common situations: Corporate npm proxies that recompute metadata incorrectly; a company registry fed by a broken replication job; publishing pipelines that strip dist.integrity; npm-mirror CDNs serving stale or corrupted packuments.

Related errors

• ERR_PNPM_TARBALL_INTEGRITY
• PACQUET_IDENTITY_MISMATCH
• NAMED_REGISTRY_PACKAGE_COLLISION
• MISSING_TARBALL_INTEGRITY
• Failed to remove Windows bin shims for ${cmd}

AI-assisted analysis of pnpm/pnpm@6261b7f388 (2026-08-17). Data as JSON: /api/errors/6e02bd7b5d77865b. Report an issue: GitHub.