# Troubleshooting Model Provisioning Failures in Open Notebook: A Complete Guide

> Troubleshoot model provisioning failures in Open Notebook by verifying default configurations, credentials, and environment variables. Resolve ConfigurationError exceptions with this guide.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-30

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py), the model registry in [`open_notebook/ai/models.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`.

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.).

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/key_provider.py) (lines 28-73). Update the credential's `provider` field accordingly.

## Practical Code Examples for Debugging

### Basic Usage with Error Handling

```python
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

```python
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

```python
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

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py) | Core provisioning logic and error handling | [View on GitHub](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py) |
| [`open_notebook/ai/models.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/models.py) | Model registry, default-model lookup, credential integration | [View on GitHub](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/models.py) |
| [`open_notebook/ai/key_provider.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/key_provider.py) | Loads DB-stored credentials into environment variables | [View on GitHub](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/key_provider.py) |
| [`open_notebook/domain/credential.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/domain/credential.py) | Schema for provider credentials and decryption | [View on GitHub](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/domain/credential.py) |

## 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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.