HKUDS/DeepTutor · critical · LLMConfigError

No effective LLM endpoint resolved. Please configure base_ur

Error message

No effective LLM endpoint resolved. Please configure base_url or provider defaults.

What it means

The resolver produced a model but no effective endpoint URL, and the provider is not in oauth mode (oauth users authenticate via tokens, so no base URL is needed). Since every other mode issues HTTP calls against effective_url, an empty one is fatal and LLMConfigError is raised with guidance to configure base_url or rely on provider defaults.

Source

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

    """
    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,
        api_key=resolved.api_key,
        base_url=resolved.base_url,
        effective_url=resolved.effective_url,
        binding=resolved.binding,

View on GitHub (pinned to 3e82f13042)

Solutions

Set base_url for the provider in Settings (e.g. http://localhost:11434/v1 for Ollama).
If the provider is standard, ensure its name matches a known default so effective_url can be derived.
Check the profile JSON for an empty base_url overriding a default and remove the empty key.
For OAuth-based access, set provider_mode to 'oauth' so the URL requirement is skipped.

Example fix

// before
# profile: {"provider": "local", "model": "llama3"}

# after
# profile: {"provider": "local", "model": "llama3", "base_url": "http://localhost:11434/v1"}

Defensive patterns

Strategy: validation

Validate before calling

resolved = resolve_llm_runtime_config()
if not resolved.effective_url and resolved.provider_mode != "oauth":
    raise RuntimeError(
        f"Provider '{resolved.provider_name}' needs a base_url (e.g. http://localhost:11434/v1)"
    )
cfg = get_llm_config()

Type guard

def has_effective_url(resolved) -> bool:
    return bool(getattr(resolved, "effective_url", None)) or resolved.provider_mode == "oauth"

Try / catch

try:
    cfg = get_llm_config()
except LLMConfigError as e:
    if "No effective LLM endpoint" in str(e):
        set_provider_base_url(default_local_url)
    raise

Prevention

Require base_url in provider-creation forms for custom providers.
Remove empty-string base_url keys from migrated settings rather than keeping them.
Use OAuth mode only when the flow genuinely supplies auth without a URL.

When it happens

Trigger: A custom/local provider whose base_url was never set; a provider entry missing from the defaults table so no fallback URL applies; base_url saved as an empty string overriding a default; whitespace-only URL treated as falsy downstream.

Common situations: Adding a new or self-hosted provider without specifying its endpoint; settings field renamed from url to base_url during migration; pointing at an internal gateway whose address lives in an env var that is unset.

Related errors

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