pypa/pip · error · ELFInvalid

unrecognized capacity

Error message

unrecognized capacity ({self.capacity}) or encoding ({self.encoding})

What it means

Bytes 4 and 5 of the ELF identification array specify EI_CLASS (1=32-bit, 2=64-bit) and EI_DATA (1=little-endian, 2=big-endian). ELFFile looks up a struct format tuple keyed by (capacity, encoding). Values 0 and 3+ are reserved/invalid per the ELF spec. If the pair is absent from the lookup dict, KeyError is caught and re-raised as ELFInvalid showing both values.

Solutions

  1. Inspect bytes 4-5 of the file to understand the capacity/encoding values before parsing
  2. Fall back to a full-featured ELF parser like pyelftools for unusual variants
  3. Skip files with unsupported class/encoding values in batch processing

Example fix

# before
elf = ELFFile(f)  # raises on unusual EI_CLASS/EI_DATA

# after
import struct
f.seek(4)
ei_class, ei_data = struct.unpack("BB", f.read(2))
f.seek(0)
if ei_class not in (1, 2) or ei_data not in (1, 2):
    print(f"Unsupported ELF class={ei_class} data={ei_data}, skipping")
    continue
elf = ELFFile(f)
Defensive patterns

Strategy: validation

Validate before calling

import struct

def validate_elf_class_encoding(path):
    with open(path, "rb") as f:
        f.seek(4)
        ei_class, ei_data = struct.unpack("BB", f.read(2))
    if ei_class not in (1, 2):
        raise ValueError(f"Unsupported ELF class: {ei_class}")
    if ei_data not in (1, 2):
        raise ValueError(f"Unsupported ELF data encoding: {ei_data}")

Try / catch

from packaging._elffile import ELFFile, ELFInvalid

try:
    elf = ELFFile(f)
except ELFInvalid as e:
    if "unrecognized capacity" in str(e):
        # unsupported architecture; fall back to pyelftools
        elf = None

Prevention

When it happens

Trigger: An ELF file whose EI_CLASS (byte 4) or EI_DATA (byte 5) is 0 (ELFCLASSNONE/ELFDATANONE) or any value >2. Happens with deliberately malformed/fuzzed ELF files, unusual embedded firmware, or non-standard toolchains.

Common situations: Analyzing obfuscated or packed malware, processing exotic embedded firmware, handling ELF files from non-standard compilers that use reserved EI_CLASS/EI_DATA values.

Related errors

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/d2de542036956761. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_vendor/packaging/_elffile.py:70

        magic = bytes(ident[:4])
        if magic != b"\x7fELF":
            raise ELFInvalid(f"invalid magic: {magic!r}")

        self.capacity = ident[4]  # Format for program header (bitness).
        self.encoding = ident[5]  # Data structure encoding (endianness).

        try:
            # e_fmt: Format for the ELF header.
            # p_fmt: Format for a program header.
            # p_idx: Indexes to find p_type, p_offset, and p_filesz.
            e_fmt, self._p_fmt, self._p_idx = {
                (1, 1): ("<HHIIIIIHHH", "<IIIIIIII", (0, 1, 4)),  # 32-bit LSB.
                (1, 2): (">HHIIIIIHHH", ">IIIIIIII", (0, 1, 4)),  # 32-bit MSB.
                (2, 1): ("<HHIQQQIHHH", "<IIQQQQQQ", (0, 2, 5)),  # 64-bit LSB.
                (2, 2): (">HHIQQQIHHH", ">IIQQQQQQ", (0, 2, 5)),  # 64-bit MSB.
            }[(self.capacity, self.encoding)]
        except KeyError as e:
            raise ELFInvalid(
                f"unrecognized capacity ({self.capacity}) or encoding ({self.encoding})"
            ) from e

        try:
            (
                _,
                self.machine,  # Architecture type.
                _,
                _,
                self._e_phoff,  # Offset of program header.
                _,
                self.flags,  # Processor-specific flags.
                _,
                self._e_phentsize,  # Size of a program header entry.
                self._e_phnum,  # Number of program headers.
            ) = self._read(e_fmt)
        except struct.error as e:
            raise ELFInvalid("unable to parse machine and section information") from e

View on GitHub (pinned to f399c37189)