pnpm/pnpm · critical · PnpmError

PATH_TRAVERSAL

PATH_TRAVERSAL

Error message

Refusing to extract path "${targetPath}" - absolute paths are not allowed

What it means

During extraction of a binary package archive, an entry name (or prefix) is an absolute path (path.isAbsolute(targetPath)), which would make extraction write to a fixed location outside the destination directory. validatePathSecurity rejects it before any file is written. Well-formed archives never contain absolute entry names, so this almost always indicates a malicious or badly packed archive.

Source

Thrown at pnpm11/fetching/binary-fetcher/src/index.ts:251

  if (!regex.global && !regex.sticky) {
    return (input) => regex.test(input)
  }
  const safeFlags = regex.flags.replace(/[gy]/g, '')
  const clone = new RegExp(regex.source, safeFlags)
  return (input) => clone.test(input)
}

/**
 * Validates that a path does not escape the base directory via path traversal.
 *
 * @param basePath - The base directory that should contain the target
 * @param targetPath - The relative path to validate
 * @throws {PnpmError} When path traversal is detected
 */
function validatePathSecurity (basePath: string, targetPath: string): void {
  // Explicitly reject absolute paths - they should never be allowed as prefixes or entry names
  if (path.isAbsolute(targetPath)) {
    throw new PnpmError('PATH_TRAVERSAL',
      `Refusing to extract path "${targetPath}" - absolute paths are not allowed`)
  }
  const normalizedTarget = path.resolve(basePath, targetPath)
  if (!isSubdir(basePath, normalizedTarget) && normalizedTarget !== basePath) {
    throw new PnpmError('PATH_TRAVERSAL',
      `Refusing to extract path "${targetPath}" outside of target directory`)
  }
}

View on GitHub (pinned to 5b11d3a15b)

Solutions

Treat the dependency as untrusted: remove it, and report it if it came from a third party
If you control the artifact, repack it with relative entry names
As a mitigation, add an archiveFilters entry to exclude the offending paths if the rest of the artifact is legitimate

Example fix

# repacking with relative paths
# before - packed with absolute names
tar czf pkg.tgz /usr/share/pkg

# after
cd /usr/share && tar czf pkg.tgz pkg

Defensive patterns

Strategy: try-catch

Validate before calling

import path from 'node:path'

// scan entry names before extracting an archive you process yourself
function hasAbsoluteEntries (entryNames: string[]): boolean {
  return entryNames.some(name => path.isAbsolute(name))
}

Try / catch

catch code === 'PATH_TRAVERSAL'; do not retry — quarantine the package, audit its provenance and publisher, and remove it from the dependency graph

Prevention

Consume binary archives only from trusted publishers and pinned integrity values
Keep allowBuilds and archiveFilters policies tight so unvetted artifacts cannot execute or extract
If you publish archives yourself, pack with relative entry names and verify with a listing step

When it happens

Trigger: A zip/tarball dependency whose entries include paths like /etc/init.d/x or Windows drive-absolute paths, or zip entries stored with a leading slash, extracted by the binary fetcher.

Common situations: Malicious packages trying to plant files outside node_modules; archives packed with absolute paths by broken tooling; zip processing tools that rewrite entry names.

Related errors

AI-assisted analysis of pnpm/pnpm@5b11d3a15b (2026-08-16). Data as JSON: /api/errors/ee536f4456e73b5c. Report an issue: GitHub.