ComposioHQ/composio · error · UnsafeZipEntryError

UnsafeZipEntryError: ${entry.fileName}

Error message

UnsafeZipEntryError: ${entry.fileName}

What it means

extractZipSafely refuses to extract a zip entry whose external file attributes mark it as a symlink. Symlinks in archives are a classic zip-slip / arbitrary-write vector, so extraction is aborted with UnsafeZipEntryError for that entry's fileName.

Source

Thrown at ts/packages/cli/src/utils/extract-zip-safely.ts:58

    this.name = 'UnsafeZipEntryError';
  }
}

/**
 * Whether a zip entry's external attributes describe a symbolic link.
 *
 * Archives written on Windows leave the Unix mode bits empty, which reads as a
 * regular file — the correct answer, since such an archive has no symlinks.
 */
export const isSymlinkZipEntry = (externalFileAttributes: number): boolean =>
  ((externalFileAttributes >>> UNIX_MODE_SHIFT) & FILE_TYPE_MASK) === SYMLINK_FILE_TYPE;

export const extractZipSafely = (zipPath: string, dir: string): Promise<void> =>
  extractZip(zipPath, {
    dir,
    onEntry: entry => {
      if (isSymlinkZipEntry(entry.externalFileAttributes)) {
        throw new UnsafeZipEntryError(entry.fileName);
      }
    },
  });

View on GitHub (pinned to 64b1b85502)

Solutions

1. Re-package the archive without symlinks (dereference them before zipping)
2. Extract with a different tool if the symlinks are trusted and intentional
3. Inspect the zip (e.g. unzip -l / zipinfo) to identify the offending entry

Example fix

// before
zip -ry out.zip dir/; // stores symlinks
// after
zip -r out.zip dir/; // dereferences symlinks into real files

// Pre-scan entries before extracting
const list = await yauzl/yauzl-based scan; // reject symlink entries (mode & 0xF000 === 0xA000)

const isSymlink = (attrs: number) => (attrs >>> 16 & 0xF000) === 0xA000;

catch (e) { if (e instanceof UnsafeZipEntryError) { /* quarantine archive */ } else throw e; }

When it happens

Trigger: Calling extractZipSafely on an archive that contains at least one symlink entry (Unix mode bits set in externalFileAttributes).

Common situations: Extracting downloaded CLI release archives, third-party zips, or artifacts packed on macOS/Linux tools that store symlinks; supply-chain or security-hardened extraction.

Related errors

• The signature provided is invalid. Please ensure you are usi
• Unsafe path component: {e}
• Refusing to build a path from an empty or non-string {label}
• Refusing to build a path from a {label} containing path sepa
• Refusing to build a path from an unsafe {label}: {value!r}.

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/36831b25969a510e. Report an issue: GitHub.