Troubleshooting Model Provisioning Failures in Open Notebook: A Complete Guide

Model provisioning failures in Open Notebook always surface as ConfigurationError exceptions and can be resolved by verifying your default model configuration, credential records, and provider environment variables.

Open Notebook dynamically resolves AI models at runtime through a centralized provisioning system. When troubleshooting model provisioning failures, you need to understand the pipeline spanning open_notebook/ai/provision.py, the model registry in open_notebook/ai/models.py, and the credential handling layer. This guide walks through each failure mode with specific file paths and actionable fixes.

How the Model Provisioning Pipeline Works

The provisioning flow follows a strict sequence across multiple modules:

1. Content measurement – token_count in open_notebook/utils/__init__.py calculates input size
2. Model selection – provision_langchain_model (lines 10-34) chooses based on token count, explicit model_id, or default type
3. Default lookup – ModelManager.get_default_model queries the DefaultModels table (lines 21-48 in models.py)
4. Credential resolution – ModelManager.get_model fetches linked Credential records (lines 20-28)
5. Environment preparation – provision_provider_keys populates expected env vars (lines 46-81 in key_provider.py)
6. Factory instantiation – Esperanto's AIFactory.create_language builds the concrete model
7. LangChain conversion – model.to_langchain() returns a BaseChatModel for downstream use

If any step fails, the system raises a ConfigurationError with a message pointing to the specific UI location for fixing the issue.

Common Failure Modes and Fixes

No Default Model Configured for the Requested Type

Where it occurs: provision_langchain_model at lines 38-44 in open_notebook/ai/provision.py

Why it happens: The DefaultModels record in the database lacks a value for the requested default_type (e.g., chat, embedding, large_context).

How to fix: Open the UI and navigate to Settings → Models, then set a default model for the missing type. Alternatively, insert a record manually via the API at /settings/models.

from open_notebook.ai.models import model_manager

# Debug: Check current defaults

defaults = await model_manager.get_defaults()
print("Default chat model:", defaults.default_chat_model)
print("Large-context model:", defaults.large_context_model)

Selected Model ID Does Not Exist or Is Mis‑typed

Where it occurs: ModelManager.get_model at lines 23-31 in open_notebook/ai/models.py

Why it happens: The stored model_id points to a record that was deleted or never created.

How to fix: Verify the model ID with GET /models/{id}. If missing, create a new model via the UI or API, then update the default configuration to reference the valid ID.

Model Type Mismatch (Non‑Language Model Where Chat Is Required)

Where it occurs: Type check after selection at lines 50-56 in open_notebook/ai/provision.py

Why it happens: model_manager.get_* returned a model that is not a LanguageModel (for example, an embedding model instead of a chat model).

How to fix: Ensure the model's type field in the database is "language" for chat/LLM usage. Either change the type column directly or select a different model with the correct type.

Missing Provider Credentials

Where it occurs: ModelManager.get_model credential fetch at lines 20-28 in open_notebook/ai/models.py

Why it happens: The model record references a credential that cannot be loaded due to a wrong ID or decryption error.

How to fix: Add a valid Credential record for the provider. See open_notebook/domain/credential.py for the schema, or update the existing record's api_key field through the Credentials UI.

Credential Present but Environment Variables Not Set

Where it occurs: key_provider.provision_provider_keys at lines 46-81 in open_notebook/ai/key_provider.py

Why it happens: The code falls back to process environment variables; if none exist, the underlying Esperanto provider raises an authentication error.

How to fix: Use await provision_provider_keys("<provider>") at startup, or set the required environment variable manually (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.).

from open_notebook.ai.key_provider import provision_provider_keys

# Pre-load credentials into environment before model creation

await provision_provider_keys("openai")

Model Factory Raises Internal Error (Unsupported Provider)

Where it occurs: ModelManager.get_model final if/elif block at lines 50-75 in open_notebook/ai/models.py

Why it happens: The provider name stored in the database does not correspond to an Esperanto-supported provider or is misspelled.

How to fix: Confirm the provider string matches one of the supported keys defined in PROVIDER_CONFIG in key_provider.py (lines 28-73). Update the credential's provider field accordingly.

Practical Code Examples for Debugging

Basic Usage with Error Handling

from open_notebook.ai.provision import provision_langchain_model
from open_notebook.exceptions import ConfigurationError

async def get_chat_model(text: str):
    try:
        # No explicit model_id → uses default chat model

        chat_model = await provision_langchain_model(
            content=text,
            model_id=None,
            default_type="chat",
            temperature=0.7,
        )
        return chat_model
    except ConfigurationError as exc:
        # Log shows UI path for fixing the issue

        logger.error(f"Model provisioning error: {exc}")
        raise

Force a Specific Model by ID

model = await provision_langchain_model(
    content=some_long_text,
    model_id="model-12345",          # ID of a LanguageModel stored in DB

    default_type="chat",
)

Manual Key Provisioning for Direct Esperanto Access

from open_notebook.ai.key_provider import provision_provider_keys
from esperanto import AIFactory

# Load DB credentials into environment

await provision_provider_keys("openai")

# Create model without going through ModelManager

lm = AIFactory.create_language(
    model_name="gpt-4o",
    provider="openai",
    config={},               # optional extra params

)

Quick Credential Verification

from open_notebook.ai.key_provider import get_api_key

key = await get_api_key("anthropic")
if not key:
    logger.warning("Anthropic API key is not set – check Credentials UI")

Key Source Files Reference

File	Role	Direct Link
open_notebook/ai/provision.py	Core provisioning logic and error handling	View on GitHub
open_notebook/ai/models.py	Model registry, default-model lookup, credential integration	View on GitHub
open_notebook/ai/key_provider.py	Loads DB-stored credentials into environment variables	View on GitHub
open_notebook/domain/credential.py	Schema for provider credentials and decryption	View on GitHub

Summary

• Model provisioning failures in Open Notebook always raise ConfigurationError with specific messages pointing to the fix location
• Default model configuration lives in the DefaultModels table; verify via Settings → Models in the UI or through model_manager.get_defaults()
• Credential resolution depends on valid records in open_notebook/domain/credential.py and proper environment variable setup via provision_provider_keys
• Type mismatches occur when embedding models are selected for chat tasks; ensure type="language" in the database
• Provider names must match keys in PROVIDER_CONFIG (key_provider.py lines 28-73) or factory instantiation fails

Frequently Asked Questions

Why does Open Notebook throw a ConfigurationError when I try to use a model?

Open Notebook raises ConfigurationError when the provisioning pipeline cannot resolve a valid model. According to the open_notebook/ai/provision.py source code at lines 38-44, this typically means no default model is configured for the requested type (chat, embedding, or large_context). Navigate to Settings → Models in the UI and set a default for the missing type, or use the /settings/models API endpoint to configure it programmatically.

How do I verify that my API credentials are properly loaded?

Check credential availability using the get_api_key function from open_notebook/ai/key_provider.py. If the key is missing, run await provision_provider_keys("<provider>") before any model calls, or set the environment variable directly (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.). The credential record itself is defined in open_notebook/domain/credential.py and must reference a valid provider name from PROVIDER_CONFIG.

What causes "model type mismatch" errors in the logs?

This error originates at lines 50-56 in open_notebook/ai/provision.py when the selected model is not a LanguageModel instance. For example, an embedding model cannot serve chat requests. Fix this by ensuring the model's type field in the database equals "language", or select a different model ID that corresponds to a chat-capable model.

Can I use a model without going through the default model system?

Yes. Pass an explicit model_id parameter to provision_langchain_model as shown in lines 10-34 of open_notebook/ai/provision.py. The function skips default lookup when model_id is provided, proceeding directly to credential resolution and factory instantiation. Ensure the ID exists in the database via GET /models/{id} before calling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}