headroomlabs-ai/headroom · error · ValueError

Language '{language}' is quarantined for code-aware compress

Error message

Language '{language}' is quarantined for code-aware compression.

What it means

Raised by _get_parser when the requested language name is in the hardcoded quarantine set _UNSAFE_TREE_SITTER_LANGUAGES (currently frozenset({"perl"}) at code_compressor.py:106). These grammars are known to hang or crash the tree-sitter parser, so Headroom refuses to build a code-aware parser for them before doing anything else. It is a ValueError thrown deliberately ahead of any parsing work.

Source

Thrown at headroom/transforms/code_compressor.py:137

    We use the stock ``tree_sitter.Parser`` (which returns standard
    ``tree_sitter.Node`` / ``tree_sitter.Tree`` with property access) and
    set its language via ``tree_sitter_language_pack.get_language()``.
    Storing one parser per (thread, language) satisfies the ``unsendable``
    contract with negligible extra memory.

    Args:
        language: Language name (e.g., 'python', 'javascript').

    Returns:
        Configured ``tree_sitter.Parser`` bound to the current thread.

    Raises:
        ImportError: If tree-sitter is not installed.
        ValueError: If language is not supported.
    """
    if language in _UNSAFE_TREE_SITTER_LANGUAGES:
        raise ValueError(f"Language '{language}' is quarantined for code-aware compression.")
    # NOTE: guard on importability (not _check_tree_sitter_available), because
    # _check_tree_sitter_available now performs a real end-to-end parse via
    # _get_parser; guarding on it here would recurse.
    if not _tree_sitter_importable():
        raise ImportError(
            "tree-sitter is not installed. Install with: pip install headroom-ai[code]\n"
            "This adds ~50MB for tree-sitter grammars."
        )

    parsers: dict[str, Any] | None = getattr(_tree_sitter_local, "parsers", None)
    if parsers is None:
        parsers = {}
        _tree_sitter_local.parsers = parsers

    if language not in parsers:
        try:
            from tree_sitter import Parser
            from tree_sitter_language_pack import get_language

View on GitHub (pinned to 322425c43b)

Solutions

1. Exclude Perl from code-aware compression (let it fall through to the generic/text compression path) — do not request a tree-sitter parser for it.
2. If you control the input, pre-filter language="perl" before calling the compressor API.
3. Do not attempt to work around by renaming the language; the quarantine exists because the grammar itself is unsafe.

Example fix

# before
parser = _get_parser("perl")  # ValueError: quarantined

# after
from headroom.transforms.code_compressor import _UNSAFE_TREE_SITTER_LANGUAGES
if language in _UNSAFE_TREE_SITTER_LANGUAGES:
    text = compress_as_plain_text(source)  # non-code-aware path
else:
    parser = _get_parser(language)

from headroom.transforms.code_compressor import _UNSAFE_TREE_SITTER_LANGUAGES
if language in _UNSAFE_TREE_SITTER_LANGUAGES:
    language = None  # route to plain-text compression

def is_safe_treesitter_language(lang: str) -> bool:
    return lang not in _UNSAFE_TREE_SITTER_LANGUAGES

try:
    parser = _get_parser(language)
except ValueError as e:
    if "quarantined" in str(e):
        parser = None  # fall back to non-code-aware compression
    else:
        raise

When it happens

Trigger: Calling _get_parser('perl') (or any future language added to _UNSAFE_TREE_SITTER_LANGUAGES) — i.e. routing Perl source into code-aware compression that eventually requests a tree-sitter parser for it.

Common situations: Pointing Headroom's code-aware compression at a Perl codebase, or a config that maps .pl/.pm files to the code compressor. The grammar is quarantined rather than merely unsupported because the perl grammar causes real runtime failures, not just bad parses.

Related errors

• Language '{language}' is not supported by tree-sitter. Suppo
• invalid pipeline config TOML: {0}
• recommendations file not found: {0}
• bedrock_eventstream_parse_failed
• items_json must be JSON: {e}

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/b51446f853245441. Report an issue: GitHub.