nodejs/node · error · ExceptionGroup

unparsed

Error message

unparsed

What it means

An ExceptionGroup raised by Metadata.from_email when the parsed email contains header keys that parse_email could not map to a known raw metadata field. Each unrecognized or invalid header becomes an InvalidMetadata entry, and the whole group is raised under the message 'unparsed'.

Source

Thrown at tools/gyp/pylib/packaging/metadata.py:727

    ) -> "Metadata":
        """Parse metadata from email headers.

        If *validate* is true, the metadata will be validated. All exceptions
        related to validation will be gathered and raised as an :class:`ExceptionGroup`.
        """
        raw, unparsed = parse_email(data)

        if validate:
            exceptions: list[Exception] = []
            for unparsed_key in unparsed:
                if unparsed_key in _EMAIL_TO_RAW_MAPPING:
                    message = f"{unparsed_key!r} has invalid data"
                else:
                    message = f"unrecognized field: {unparsed_key!r}"
                exceptions.append(InvalidMetadata(unparsed_key, message))

            if exceptions:
                raise ExceptionGroup("unparsed", exceptions)

        try:
            return cls.from_raw(raw, validate=validate)
        except ExceptionGroup as exc_group:
            raise ExceptionGroup(
                "invalid or unparsed metadata", exc_group.exceptions
            ) from None

    metadata_version: _Validator[_MetadataVersion] = _Validator()
    """:external:ref:`core-metadata-metadata-version`
    (required; validated to be a valid metadata version)"""
    name: _Validator[str] = _Validator()
    """:external:ref:`core-metadata-name`
    (required; validated using :func:`~packaging.utils.canonicalize_name` and its
    *validate* parameter)"""
    version: _Validator[version_module.Version] = _Validator()
    """:external:ref:`core-metadata-version` (required)"""
    dynamic: _Validator[Optional[List[str]]] = _Validator(

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Inspect the ExceptionGroup's sub-exceptions to list the offending header keys.
2. Remove or correct the unrecognized headers in the source metadata.
3. Pass validate=False to from_email to accept unparsed fields silently.
4. Upgrade the packaging library if the header is valid in a newer core-metadata spec.

Example fix

# before
meta = Metadata.from_email(data)

# after
meta = Metadata.from_email(data, validate=False)

from packaging.metadata import _EMAIL_TO_RAW_MAPPING
def known_headers(msg):
    return [k for k in msg if k not in _EMAIL_TO_RAW_MAPPING]  # empty => safe

try:
    meta = Metadata.from_email(data, validate=True)
except ExceptionGroup as eg:
    unknown = [e.field for e in eg.exceptions]
    # strip unknown headers from source, or pass validate=False

When it happens

Trigger: Calling Metadata.from_email(data, validate=True) where data contains email headers not in _EMAIL_TO_RAW_MAPPING (truly unknown fields) or known fields whose data failed to parse into raw form. The for-loop over 'unparsed' builds an InvalidMetadata per key.

Common situations: A METADATA file with custom/typo headers (e.g. 'X-Something' or a misspelled 'Classifier'), or headers produced by a newer core-metadata revision than this vendored packaging knows about.

Related errors

• invalid metadata
• invalid or unparsed metadata
• key must be ascii string
• expected headers to be an array
• ${optionName} must be an array

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/8b7f5baa1cb8b6b8. Report an issue: GitHub.