usestrix/strix · error · ValueError

extra_system_prompt_context cannot override built-in scope k

Error message

extra_system_prompt_context cannot override built-in scope keys: {sorted(reserved_keys)}

What it means

Raised by _merge_root_prompt_context (strix/core/runner.py:73) when the caller-supplied extra_system_prompt_context dict contains keys that collide with the built-in scope context keys. The scope context carries authoritative scan facts (target, mode, whitebox flag, etc.), so allowing user extras to overwrite them would silently corrupt the root agent's instructions. It is a plain ValueError raised at scan setup, before any LLM call.

Source

Thrown at strix/core/runner.py:73

    from agents.result import RunResultBase

    from strix.runtime.status import StatusSink


logger = logging.getLogger(__name__)

StreamEventSink = Callable[[str, Any], None]


def _merge_root_prompt_context(
    scope_context: dict[str, Any],
    extra_system_prompt_context: dict[str, Any] | None,
) -> dict[str, Any]:
    if not extra_system_prompt_context:
        return scope_context
    reserved_keys = scope_context.keys() & extra_system_prompt_context.keys()
    if reserved_keys:
        raise ValueError(
            "extra_system_prompt_context cannot override built-in scope keys: "
            f"{sorted(reserved_keys)}",
        )
    return {**scope_context, **extra_system_prompt_context}


def _compose_root_instructions_override(
    root_instructions_override: str | None,
    *,
    skills: list[str],
    scan_mode: str,
    is_whitebox: bool,
    interactive: bool,
    system_prompt_context: dict[str, Any],
) -> str | None:
    if root_instructions_override is None:
        return None

View on GitHub (pinned to 8551339130)

Solutions

Rename the offending keys in extra_system_prompt_context so they do not shadow built-in scope keys — the error message lists the exact colliding keys (sorted).
If you need to change scan behavior, use the dedicated parameters (target, scan_mode, root_instructions_override) instead of prompt-context keys.
Print/inspect the scope_context keys for your scope version and diff them against your extras before launching.

Example fix

# before
run_strix_scan(..., extra_system_prompt_context={"target": "https://x.com"})

# after
run_strix_scan(..., extra_system_prompt_context={"engagement_notes": "focus on auth endpoints"})

Defensive patterns

Strategy: validation

Validate before calling

scope_keys = set(scope_context)  # keys the selected scope injects
extra = {k: v for k, v in (extra_system_prompt_context or {}).items()}
clash = scope_keys & set(extra)
assert not clash, f'rename these keys: {sorted(clash)}'

Type guard

def is_scope_override_error(exc: BaseException) -> bool:
    return isinstance(exc, ValueError) and 'cannot override built-in scope keys' in str(exc)

Try / catch

try:
    run_strix_scan(..., extra_system_prompt_context=extra)
except ValueError as exc:
    if 'cannot override built-in scope keys' in str(exc):
        clash = parse_keys_from_message(str(exc))
        extra = {k: v for k, v in extra.items() if k not in clash}
        run_strix_scan(..., extra_system_prompt_context=extra)
    else:
        raise

Prevention

Namespace your extra keys with a prefix (e.g. 'corp_') to avoid collisions.
Re-run the key diff after upgrading Strix, since scopes gain built-in keys over time.

When it happens

Trigger: Calling run_strix_scan(..., extra_system_prompt_context={'target': ..., ...}) or configuring extra context keys in settings that overlap with the keys the selected scope already injects (scope_context.keys() & extra.keys() is non-empty).

Common situations: Embedding Strix programmatically and passing generic keys like 'target', 'scan_mode', or 'instructions' that the scope also sets; upgrading Strix versions where a scope gained new built-in keys that now collide with previously-working extras.

Related errors

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/459efb10cc325f1b. Report an issue: GitHub.