headroomlabs-ai/headroom · error · ValueError

position must be one of {POSITIONS}, got {position!r}

Error message

position must be one of {POSITIONS}, got {position!r}

What it means

splice_payload() in headroom.evals.adversarial_grid validates its position argument against the POSITIONS constant (head/middle/tail) and raises ValueError with the allowed set and the offending value for anything else. This is pure input validation before any carrier/payload splicing happens (_splice_json and _splice_lines are only reached with a valid position).

Source

Thrown at headroom/evals/adversarial_grid.py:193

    if not dicts:
        return None
    target = dicts[_position_index(len(dicts), position)]
    target["note"] = payload
    return json.dumps(data, indent=2)


def _splice_lines(carrier: str, payload: str, position: str) -> str:
    lines = carrier.splitlines()
    if not lines:
        return payload
    at = _position_index(len(lines), position) + (1 if position == "head" else 0)
    return "\n".join(lines[:at] + [payload] + lines[at:])


def splice_payload(carrier: str, payload: str, position: str) -> str:
    """Embed a payload into a carrier at head/middle/tail."""
    if position not in POSITIONS:
        raise ValueError(f"position must be one of {POSITIONS}, got {position!r}")
    spliced = _splice_json(carrier, payload, position)
    if spliced is not None:
        return spliced
    return _splice_lines(carrier, payload, position)


def _benign_lines(carrier: str) -> list[str]:
    lines = [ln.strip() for ln in carrier.splitlines()]
    lines = [ln for ln in lines if len(ln) >= _BENIGN_LINE_MIN_CHARS]
    if len(lines) <= _BENIGN_LINE_SAMPLE:
        return lines
    step = len(lines) / _BENIGN_LINE_SAMPLE
    return [lines[int(i * step)] for i in range(_BENIGN_LINE_SAMPLE)]


def _compression_ratio(original: str, compressed: str) -> float:
    if not original:
        return 1.0

View on GitHub (pinned to 322425c43b)

Solutions

1. Use one of the exact allowed values: 'head', 'middle', or 'tail' (match case exactly)
2. Validate user-supplied position against the module's POSITIONS constant before calling splice_payload — import it rather than hardcoding the list
3. Normalize input early: `position = position.strip().lower()` then check membership

Example fix

# before
splice_payload(carrier, payload, position="start")
# ValueError: position must be one of ('head','middle','tail'), got 'start'

# after
from headroom.evals.adversarial_grid import POSITIONS
position = position.strip().lower()
assert position in POSITIONS, f"position must be one of {POSITIONS}"
splice_payload(carrier, payload, position=position)

from headroom.evals.adversarial_grid import POSITIONS

position = str(position).strip().lower()
if position not in POSITIONS:
    raise ValueError(f"position must be one of {POSITIONS}, got {position!r}")
splice_payload(carrier, payload, position)

from headroom.evals.adversarial_grid import POSITIONS

def is_valid_position(value: object) -> bool:
    return isinstance(value, str) and value in POSITIONS

When it happens

Trigger: Calling splice_payload(carrier, payload, position) with e.g. 'top', 'start', 'end', 'center', 'Head' (case-sensitive), or None — any string not exactly in POSITIONS. Programmatic callers deriving position from config files or CLI flags most often hit it.

Common situations: YAML/JSON eval config with a typo'd position field; passing 0/1/2 indices instead of names; case mismatch ('Middle'); new positions added to a fork but POSITIONS not updated.

Related errors

• items_json must be JSON: {e}
• doc_json must be JSON: {e}
• target_savings must be between 0 and 1
• Unknown provider: {self.provider}
• Unknown provider: {self.llm_config.provider}

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