General

Debugging Instructor Applications

Learn how to debug Instructor applications with hooks, logging, and exception handling. Practical techniques for inspecting inputs, outputs, and retries.

promptBeginner5 min to valuemarkdown

0 views

Feb 1, 2026

Additional Files (17)

View Original Source

Related Skills

General

PromptBeginner5 minmarkdown

<h1 align="center">

Jan 12, 2026

General

PromptBeginner5 minmarkdown

2. Apply Deepthink Protocol (reason about dependencies

risks

Jan 15, 2026

General

PromptBeginner5 minmarkdown

- Identify gaps

ambiguities

Jan 15, 2026

Additional Files (17)

title: Debugging Instructor Applications description: Learn how to debug Instructor applications with hooks, logging, and exception handling. Practical techniques for inspecting inputs, outputs, and retries.

Debugging

This guide shows how to quickly inspect inputs/outputs, capture retries, and reproduce failures when working with Instructor. It focuses on practical techniques using hooks, logging, and exception data.

Enable Logs

Quick Debug Mode (Recommended)

The fastest way to enable debug logging is with the

INSTRUCTOR_DEBUG

environment variable:

export INSTRUCTOR_DEBUG=1
python your_script.py

Or inline:

INSTRUCTOR_DEBUG=1 python your_script.py

This automatically enables debug logging with correlation IDs for request tracing.

Manual Debug Configuration

You can also use the standard Python

logging

module for more control:

import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("instructor").setLevel(logging.DEBUG)

You will see messages for:

Raw responses (provider-specific objects)
Handler/mode selection
Retry attempts and parse errors
Reask adjustments to
```
messages
```
Correlation IDs for tracing requests (format:
```
[a1b2c3d4]
```
)

Tip: Set a handler/formatter to include timestamps and module names.

Observe the Flow with Hooks

Hooks let you tap into key moments without modifying core code:

from instructor.core.hooks import HookName

# Attach one or more handlers
client.on(HookName.COMPLETION_KWARGS, lambda **kw: print("KWARGS:", kw))
client.on(HookName.COMPLETION_RESPONSE, lambda resp: print("RESPONSE:", type(resp)))
client.on(HookName.PARSE_ERROR, lambda e: print("PARSE ERROR:", e))
client.on(HookName.COMPLETION_LAST_ATTEMPT, lambda e: print("LAST ATTEMPT:", e))
client.on(HookName.COMPLETION_ERROR, lambda e: print("COMPLETION ERROR:", e))

Common uses:

Capture the final
```
kwargs
```
passed to the provider (including mode/tools/response_format).
Record raw responses (e.g., to logs or a file) for offline analysis.
Inspect parse errors and how reask modifies the next attempt.

Note: Handlers that accept

**kwargs

(or a parameter named

_instructor_meta

) receive a metadata dict with:

attempt_number

correlation_id

mode

response_model_name

. Add

**kwargs

to your handler signature to access it:

client.on(HookName.COMPLETION_KWARGS, lambda **kw: print(kw.get("_instructor_meta")))

Inspect Raw Responses

Most parsed models returned by Instructor carry the original provider response for debugging:

model = client.create(...)
raw = getattr(model, "_raw_response", None)
print(raw)

This is useful for checking provider metadata like token usage, model version, and provider-specific fields.

Handling Failures & Retries

When all retries are exhausted, an

InstructorRetryException

is raised. It includes detailed context:

from instructor.core.exceptions import InstructorRetryException

try:
    client.create(...)
except InstructorRetryException as e:
    print("Attempts:", e.n_attempts)
    print("Last completion:", e.last_completion)
    print("Create kwargs:", e.create_kwargs)  # reproducible input
    print("Failed attempts:", e.failed_attempts)  # list of (attempt, exception, completion)
    # If available, a compact trace packet to help debugging
    if hasattr(e, "trace_packet") and e.trace_packet:
        print("Trace packet:", e.trace_packet)

Use

e.create_kwargs

and

e.failed_attempts

to craft a minimal reproduction.

Minimal Reproduction Template

import openai
import instructor
from pydantic import BaseModel

class MyModel(BaseModel):
    # fields...
    pass

client = instructor.from_provider("openai/gpt-5-nano")

create_kwargs = {
    # paste from InstructorRetryException.create_kwargs
}

try:
    client.create(response_model=MyModel, **create_kwargs)
except Exception as err:
    # Inspect and iterate
    raise

This pattern captures the exact inputs that triggered a failure.

Strict vs Non-Strict Parsing

```
strict=True
```
enforces exact schema matches and can surface schema drift early.
If providers sometimes return extra fields or slightly different types (e.g., floats for ints), try
```
strict=False
```
to validate non‑strictly.

client.create(..., response_model=MyModel, strict=True)

Customizing Retries

You can pass an integer (attempt count) or a

tenacity

retrying object to control behavior:

from tenacity import Retrying, stop_after_attempt, stop_after_delay

max_retries = Retrying(stop=stop_after_attempt(3) | stop_after_delay(10))
client.create(..., max_retries=max_retries)

This is helpful when balancing latency and robustness.

Multimodal & Message Conversion

If you send images/audio/PDFs or text that may include media paths/URIs, Instructor can convert messages for provider formats.

For supported modes,
```
processing.multimodal.convert_messages
```
runs automatically.
If debugging content issues, log
```
messages
```
before and after conversion using the hooks above, and ensure media types/URIs are valid.

Caching Considerations

If you’re using a cache (

cache=...

), remember:

Successful parsed responses are stored; retrieving from cache skips the provider call.
If debugging live provider behavior, temporarily disable cache or change the cache key (e.g., tweak a message).

model = client.create(..., cache=None)

Common Troubleshooting Tips

Validate the
```
response_model.model_json_schema()
```
matches what you expect the provider to return.
Confirm
```
mode
```
is valid for your provider; mismatches can cause parsing failures.
Check provider‑side limits (max tokens/response length); incomplete outputs raise specific exceptions.
If using markdown JSON (
```
MD_JSON
```
), ensure the provider is actually returning a ```json code block.

If you need deeper visibility, add a custom handler to write kwargs/responses/errors to disk with a timestamp and correlation id.

Example: Local Debug Run

You can run a minimal, no‑network example that exercises hooks, logging, and parsing flow using a fake provider function:

File:
```
examples/debugging/run.py
```
Run:

python examples/debugging/run.py

This script:

Enables DEBUG logging for
```
instructor.*
```
Patches a fake provider
```
create
```
with
```
instructor.patch(mode=Mode.JSON)
```
Attaches hook handlers to print kwargs, response types, and parse errors
Parses a simple JSON payload into a Pydantic model and prints the result

title: Debugging Instructor Applications description: Learn how to debug Instructor applications with hooks, logging, and exception handling. Practical techniques for inspecting inputs, outputs, and retries.

Debugging

Enable Logs

Quick Debug Mode (Recommended)

The fastest way to enable debug logging is with the

INSTRUCTOR_DEBUG

environment variable:

export INSTRUCTOR_DEBUG=1
python your_script.py

Or inline:

INSTRUCTOR_DEBUG=1 python your_script.py

This automatically enables debug logging with correlation IDs for request tracing.

Manual Debug Configuration

You can also use the standard Python

logging

module for more control:

import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("instructor").setLevel(logging.DEBUG)

You will see messages for:

Raw responses (provider-specific objects)
Handler/mode selection
Retry attempts and parse errors
Reask adjustments to
```
messages
```
Correlation IDs for tracing requests (format:
```
[a1b2c3d4]
```
)

Tip: Set a handler/formatter to include timestamps and module names.

Observe the Flow with Hooks

Hooks let you tap into key moments without modifying core code:

from instructor.core.hooks import HookName

# Attach one or more handlers
client.on(HookName.COMPLETION_KWARGS, lambda **kw: print("KWARGS:", kw))
client.on(HookName.COMPLETION_RESPONSE, lambda resp: print("RESPONSE:", type(resp)))
client.on(HookName.PARSE_ERROR, lambda e: print("PARSE ERROR:", e))
client.on(HookName.COMPLETION_LAST_ATTEMPT, lambda e: print("LAST ATTEMPT:", e))
client.on(HookName.COMPLETION_ERROR, lambda e: print("COMPLETION ERROR:", e))

Common uses:

Capture the final
```
kwargs
```
passed to the provider (including mode/tools/response_format).
Record raw responses (e.g., to logs or a file) for offline analysis.
Inspect parse errors and how reask modifies the next attempt.

Note: Handlers that accept

**kwargs

(or a parameter named

_instructor_meta

) receive a metadata dict with:

attempt_number

correlation_id

mode

response_model_name

. Add

**kwargs

to your handler signature to access it:

client.on(HookName.COMPLETION_KWARGS, lambda **kw: print(kw.get("_instructor_meta")))

Inspect Raw Responses

Most parsed models returned by Instructor carry the original provider response for debugging:

model = client.create(...)
raw = getattr(model, "_raw_response", None)
print(raw)

This is useful for checking provider metadata like token usage, model version, and provider-specific fields.

Handling Failures & Retries

When all retries are exhausted, an

InstructorRetryException

is raised. It includes detailed context:

from instructor.core.exceptions import InstructorRetryException

try:
    client.create(...)
except InstructorRetryException as e:
    print("Attempts:", e.n_attempts)
    print("Last completion:", e.last_completion)
    print("Create kwargs:", e.create_kwargs)  # reproducible input
    print("Failed attempts:", e.failed_attempts)  # list of (attempt, exception, completion)
    # If available, a compact trace packet to help debugging
    if hasattr(e, "trace_packet") and e.trace_packet:
        print("Trace packet:", e.trace_packet)

Use

e.create_kwargs

and

e.failed_attempts

to craft a minimal reproduction.

Minimal Reproduction Template

import openai
import instructor
from pydantic import BaseModel

class MyModel(BaseModel):
    # fields...
    pass

client = instructor.from_provider("openai/gpt-5-nano")

create_kwargs = {
    # paste from InstructorRetryException.create_kwargs
}

try:
    client.create(response_model=MyModel, **create_kwargs)
except Exception as err:
    # Inspect and iterate
    raise

This pattern captures the exact inputs that triggered a failure.

Strict vs Non-Strict Parsing

```
strict=True
```
enforces exact schema matches and can surface schema drift early.
If providers sometimes return extra fields or slightly different types (e.g., floats for ints), try
```
strict=False
```
to validate non‑strictly.

client.create(..., response_model=MyModel, strict=True)

Customizing Retries

You can pass an integer (attempt count) or a

tenacity

retrying object to control behavior:

from tenacity import Retrying, stop_after_attempt, stop_after_delay

max_retries = Retrying(stop=stop_after_attempt(3) | stop_after_delay(10))
client.create(..., max_retries=max_retries)

This is helpful when balancing latency and robustness.

Multimodal & Message Conversion

If you send images/audio/PDFs or text that may include media paths/URIs, Instructor can convert messages for provider formats.

For supported modes,
```
processing.multimodal.convert_messages
```
runs automatically.
If debugging content issues, log
```
messages
```
before and after conversion using the hooks above, and ensure media types/URIs are valid.

Caching Considerations

If you’re using a cache (

cache=...

), remember:

Successful parsed responses are stored; retrieving from cache skips the provider call.
If debugging live provider behavior, temporarily disable cache or change the cache key (e.g., tweak a message).

model = client.create(..., cache=None)

Common Troubleshooting Tips

Validate the
```
response_model.model_json_schema()
```
matches what you expect the provider to return.
Confirm
```
mode
```
is valid for your provider; mismatches can cause parsing failures.
Check provider‑side limits (max tokens/response length); incomplete outputs raise specific exceptions.
If using markdown JSON (
```
MD_JSON
```
), ensure the provider is actually returning a ```json code block.

If you need deeper visibility, add a custom handler to write kwargs/responses/errors to disk with a timestamp and correlation id.

Example: Local Debug Run

You can run a minimal, no‑network example that exercises hooks, logging, and parsing flow using a fake provider function:

File:
```
examples/debugging/run.py
```
Run:

python examples/debugging/run.py

This script:

Enables DEBUG logging for
```
instructor.*
```
Patches a fake provider
```
create
```
with
```
instructor.patch(mode=Mode.JSON)
```
Attaches hook handlers to print kwargs, response types, and parse errors
Parses a simple JSON payload into a Pydantic model and prints the result