affaan-m/ECC · error · ValueError

requires_alpha must be boolean

Error message

requires_alpha must be boolean

What it means

Each event's 'requires_alpha' must be a real boolean (default False); allocate_placements raises ValueError('requires_alpha must be boolean') for anything else. Truthy ints like 1/0 are rejected because the library distinguishes 'not specified' from 'specified as false' and needs strict bools.

Solutions

  1. Pass Python booleans: requires_alpha=True or False (or omit the key for the default)
  2. Convert string/int flags at load time: `ra = flag in (True, 'true', 'yes', 1)` then pass bool(ra)
  3. If loading JSON from an API, coerce with `bool(event['requires_alpha'])` only after confirming it's a 0/1 or bool, else fix the producer
  4. Fix config producers to emit real booleans (unquoted YAML true/false, JSON true/false)

Example fix

// before
{"id": "bug", "requires_alpha": "true"}
// after
{"id": "bug", "requires_alpha": true}
Defensive patterns

Strategy: type-guard

Validate before calling

def coerce_bool_flag(v, default=False):
    if v is None:
        return default
    if isinstance(v, bool):
        return v
    if isinstance(v, str):
        if v.lower() in ('true', 'yes', '1'):
            return True
        if v.lower() in ('false', 'no', '0'):
            return False
    raise ValueError(f'requires_alpha must be boolean, got {v!r}')

for ev in placements:
    ev['requires_alpha'] = coerce_bool_flag(ev.get('requires_alpha'))

Type guard

def is_strict_bool(v) -> bool:
    return isinstance(v, bool)

Try / catch

try:
    resolve.allocate_placements(fps, count, placements)
except ValueError as e:
    if 'requires_alpha' in str(e):
        raise PlacementError('requires_alpha must be a strict boolean') from e
    raise

Prevention

When it happens

Trigger: Passing requires_alpha=1, 0, 'true'/'false' strings, None, or a JSON/YAML config that encodes the flag as a string or integer instead of a boolean.

Common situations: YAML configs quoting the flag ('true' → str); JSON APIs returning 0/1 from a database; shell-exported env flags parsed as strings and passed through; template systems inserting 'yes'/'no'.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/4289a0280983c8d6. Report an issue: GitHub.

Appendix: source

Thrown at skills/taste-application/scripts/tasteforge/resolve.py:121

        frames = _integer(event.get("frames"), "frames", 1)
        opacity = event.get("opacity")
        if (
            isinstance(opacity, bool)
            or not isinstance(opacity, (int, float))
            or not math.isfinite(opacity)
            or not 0 <= opacity <= 100
        ):
            raise ValueError("explicit opacity must be finite within 0..100")
        composite = _integer(event.get("composite"), "composite")
        raw_asset = event.get("asset")
        if not isinstance(raw_asset, (str, Path)) or not str(raw_asset):
            raise ValueError("asset must be a local regular file")
        asset = Path(raw_asset).expanduser().resolve()
        if not asset.is_file():
            raise ValueError(f"asset must be a local regular file: {asset}")
        alpha = event.get("requires_alpha", False)
        if not isinstance(alpha, bool):
            raise ValueError("requires_alpha must be boolean")
        key = str(asset)
        if key not in metadata:
            metadata[key] = probe(asset)
        info = metadata[key]
        if _fps(info.get("fps")) != rate:
            raise ValueError(f"asset fps differs from timeline: {asset}")
        if _integer(info.get("frames"), "asset frames", 1) < frames:
            raise ValueError(f"asset contains too few frames: {asset}")
        if alpha and info.get("has_alpha") is not True:
            raise ValueError(f"asset requires verified alpha: {asset}")
        checked.append(
            {
                "id": identifier,
                "asset": key,
                "record_frame": start,
                "frames": frames,
                "opacity": opacity,
                "composite": composite,

View on GitHub (pinned to 8321021c54)