HKUDS/DeepTutor · critical · LLMConfigError

No active LLM model is configured. Please set it in Settings

Error message

No active LLM model is configured. Please set it in Settings > Catalog.

What it means

The runtime config resolver (resolve_llm_runtime_config) returned a profile with an empty model, so _get_llm_config_from_resolver cannot construct an LLMConfig and raises LLMConfigError pointing the user at Settings > Catalog. This is the earliest and most common startup/first-call failure for cloud providers.

Source

Thrown at deeptutor/services/llm/config.py:174

    Explicitly initialize environment variables for compatibility.

    This should be called during application startup to keep OPENAI_* env vars
    aligned with current config values.
    """
    resolved = resolve_llm_runtime_config()
    if _is_openai_compatible_binding(resolved.binding):
        _set_openai_env_vars(
            resolved.api_key,
            resolved.effective_url,
            source="initialize_environment",
        )


def _get_llm_config_from_resolver() -> LLMConfig:
    """Resolve LLM config from the TutorBot-style runtime adapter."""
    resolved = resolve_llm_runtime_config()
    if not resolved.model:
        raise LLMConfigError(
            "No active LLM model is configured. Please set it in Settings > Catalog."
        )
    if not resolved.effective_url and resolved.provider_mode != "oauth":
        raise LLMConfigError(
            "No effective LLM endpoint resolved. Please configure base_url or provider defaults."
        )
    is_placeholder_key = resolved.api_key in {"", "no-key", "sk-no-key-required"}
    if (
        resolved.provider_name == "openai"
        and resolved.provider_mode == "standard"
        and is_placeholder_key
    ):
        raise LLMConfigError(
            "OpenAI API key is not configured. Set it in Settings > Catalog, "
            "or select a local provider such as Ollama."
        )
    return LLMConfig(
        model=resolved.model,

View on GitHub (pinned to 3e82f13042)

Solutions

Open Settings > Catalog in the app and select an active model (or set it in data/user/settings/*.json).
Programmatically: seed the settings file or set the model before calling get_llm_config().
Verify by calling resolve_llm_runtime_config() and checking .model is non-empty.
For local dev, select an Ollama model to avoid needing cloud credentials.

Example fix

// before
cfg = get_llm_config()  # raises on fresh install

# after
resolved = resolve_llm_runtime_config()
if not resolved.model:
    # seed settings: select e.g. gpt-4o-mini or an Ollama model
cfg = get_llm_config()

Defensive patterns

Strategy: validation

Validate before calling

from deeptutor.services.llm.config import resolve_llm_runtime_config  # or equivalent
resolved = resolve_llm_runtime_config()
if not resolved.model:
    raise RuntimeError("Select a model in Settings > Catalog before starting")
cfg = get_llm_config()

Type guard

def has_active_model(resolved) -> bool:
    return bool(getattr(resolved, "model", None) and resolved.model.strip())

Try / catch

try:
    cfg = get_llm_config()
except LLMConfigError as e:
    if "No active LLM model" in str(e):
        run_first_time_setup()  # seed settings, then retry
    raise

Prevention

Include a first-run wizard that forces model selection.
Seed a default (e.g. local Ollama model) in fresh installs.
Smoke-test get_llm_config() in CI with a fixture profile.

When it happens

Trigger: Fresh install with no model selected; settings JSON exists but the active profile's model field is empty; a provider was chosen but its model sub-selection was never made; programmatic use before any catalog setup.

Common situations: New users running their first chat before configuring anything; settings reset or migration wiping the model; CI/smoke tests instantiating the app without seeding settings.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/21533572b763ced5. Report an issue: GitHub.