What causes "base_url is required for local LLM provider" in HKUDS/DeepTutor?

Set base_url in the provider config (e.g. http://localhost:11434/v1 for Ollama) and restart.

HKUDS/DeepTutor · error · LLMConfigError

base_url is required for local LLM provider

Error message

base_url is required for local LLM provider

What it means

The local LLM provider (Ollama/llama.cpp-style backends) requires an explicit base_url because there is no default endpoint to call. complete() raises LLMConfigError before any HTTP request when base_url is empty, since it cannot construct the chat completions URL.

Source

Thrown at deeptutor/services/llm/local_provider.py:177

    """
    Complete a prompt using local LLM server.

    Uses aiohttp for better compatibility with local servers.

    Args:
        prompt: The user prompt (ignored if messages provided)
        system_prompt: System prompt for context
        model: Model name
        api_key: API key (optional for most local servers)
        base_url: Base URL for the local server
        messages: Pre-built messages array (optional)
        **kwargs: Additional parameters (temperature, max_tokens, etc.)

    Returns:
        str: The LLM response
    """
    if not base_url:
        raise LLMConfigError("base_url is required for local LLM provider")

    # Sanitize URL and build chat endpoint
    base_url = sanitize_url(base_url, model or "")
    url = build_chat_url(base_url)

    # Build headers using unified utility
    headers = build_auth_headers(api_key)

    # Build messages
    if messages:
        msg_list = messages
    else:
        msg_list = [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": prompt},
        ]

    # Build request data

View on GitHub (pinned to 3e82f13042)

Solutions

Set base_url in the provider config (e.g. http://localhost:11434/v1 for Ollama) and restart.
Check the settings JSON under data/user/settings/ for a missing/typo'd base_url key.
Verify the local server is actually running and the URL matches its API path.

Example fix

# before
provider = LocalLLMProvider(config={'model': 'llama3'})
# after
provider = LocalLLMProvider(config={'model': 'llama3', 'base_url': 'http://localhost:11434/v1'})

Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse

def can_use_local_provider(cfg: dict) -> bool:
    url = cfg.get('base_url')
    return bool(url) and bool(urlparse(url).scheme) and bool(urlparse(url).netloc)

Try / catch

from deeptutor.services.llm.local_provider import LLMConfigError
try:
    resp = await provider.complete(prompt)
except LLMConfigError as e:
    if 'base_url' in str(e):
        raise SystemExit('Configure LOCAL_LLM_BASE_URL before running') from e
    raise

Prevention

Fail fast at startup with a settings schema check requiring base_url for local providers
Keep one validated settings template per provider
Add a health-check ping to the local server during app bootstrap

When it happens

Trigger: Calling LocalLLMProvider.complete(prompt) (or stream(), which delegates to complete) with base_url=None or '' — e.g. config missing the 'base_url' key, env var LOCAL_LLM_BASE_URL unset, or a settings JSON where the field name is misspelled.

Common situations: Fresh installs where the local provider config was never filled in; switching from OpenAI to a local backend without adding the URL; loading settings from data/user/settings/*.json that predates the base_url field.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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