usestrix/strix · error · RuntimeError

Model connection failed: {exc}

Error message

Model connection failed: {exc}

What it means

Raised in runtime.py's go-path start flow when preflight_model_connection(model) raises while 'verify' is requested. The preflight (strix/interface/scan_setup.py:61) performs a minimal network call against the configured LLM before the scan begins, so misconfigured API keys, unreachable providers, or invalid model ids fail fast here instead of mid-scan. The original exception is chained and logged ('Go TUI setup model preflight failed').

Source

Thrown at strix/interface/tui/runtime.py:133

        candidate.max_turns = self.controller.max_turns
        candidate.scope_mode = self.controller.scope_mode
        candidate.diff_base = self.controller.diff_base
        existing_targets = [
            str(target["original"])
            for target in candidate.targets_info
            if isinstance(target, dict) and target.get("original")
        ]
        targets_changed = self.controller.targets != existing_targets
        model = (load_settings().llm.model or "").strip()
        # A bare prompt launches optimistically: it skips the network preflight
        # and lets any model error surface once the agent starts, like a coding
        # agent. A named target keeps the upfront check.
        if verify:
            try:
                await preflight_model_connection(model)
            except Exception as exc:
                logger.exception("Go TUI setup model preflight failed")
                raise RuntimeError(f"Model connection failed: {exc}") from exc
        # A confirmed target-less launch mounts the working directory for the
        # agent to work in, without making it a scan target.
        candidate.workspace_mount = self.controller.workspace_mount
        if targets_changed:
            # Rebuild the full typed set so path canonicalization and local
            # deduplication match the CLI.
            candidate.target = list(self.controller.targets)
            candidate.target_list = []
            build_targets_info(candidate)
        prepare_run(candidate)
        telemetry_start(candidate)

        vars(self.args).update(vars(candidate))
        self.init_run_state()
        self.start_scan()

    async def prepare_and_start(self) -> None:
        """Prepare a directly-launched scan once the TUI is on screen.

View on GitHub (pinned to 8551339130)

Solutions

1. Check the embedded {exc} text — it names the real cause (auth, 404 model, timeout)
2. Verify the key: export LLM_API_KEY correctly and confirm with a one-line curl to the provider
3. Confirm the model id is a valid LiteLLM identifier (provider-prefixed)
4. Fix network/proxy egress for the provider endpoint, then retry the start
5. As a last resort for prompt-only launches, note that verify is skipped for bare prompts — but named targets always preflight

Example fix

# before
export LLM_API_KEY="sk-wrong"
strix -t https://example.com
# -> Model connection failed: AuthenticationError ...

# after
export LLM_API_KEY="$REAL_KEY"
export STRIX_LLM="openai/gpt-4o"
strix -t https://example.com

model = (load_settings().llm.model or "").strip()
if not model or not os.environ.get("LLM_API_KEY"):
    raise SystemExit("set STRIX_LLM/<model> and LLM_API_KEY before starting")

def model_config_plausible() -> bool:
    return bool((load_settings().llm.model or "").strip()) and bool(os.environ.get("LLM_API_KEY"))

try:
    await start_scan(verify=True)
except RuntimeError as e:
    if str(e).startswith("Model connection failed:"):
        diagnose_llm_config(e)  # inspect chained exc: auth vs model-id vs network
    else:
        raise

When it happens

Trigger: Starting a scan with a named target (verify=True) while LLM_API_KEY is missing/wrong, STRIX_LLM/llm.model names an unknown model id, the provider endpoint is unreachable, or a proxy blocks the request. The exception text of the underlying failure is embedded in the message.

Common situations: Expired or mistyped API key; model string not a valid LiteLLM id (e.g. 'gpt-5' vs 'openai/gpt-5'); corporate egress proxy; provider outage; .env not loaded so key is empty; region-blocked endpoint.

Related errors

• No model configured. Set STRIX_LLM first.
• No LLM model configured. Set STRIX_LLM env or pass model= to
• Setup can no longer be changed after the scan starts
• unavailable
• extra_system_prompt_context cannot override built-in scope k

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