Cannot import instructor.exceptions. ClientError,ConfigurationError,InstructorError,ModeError,ProviderError,ValidationError

[MonsignorEduardo]

• This is actually a bug report.
• I am not getting good LLM Results
• I have tried asking for help in the community on discord or discussions and have not received a response.
• I have tried searching the documentation and have not found an answer.

Describe the bug
The documentation is "overupdated" https://python.useinstructor.com/concepts/error_handling/?h=validationerror#exception-hierarchy while the latest released version 1.8.3 doesnt https://github.com/567-labs/instructor/blob/1.8.3/instructor/exceptions.py

from instructor.exceptions import (
    ValidationError, #"ValidationError" is unknown import symbolPylance
)

[jxnl]

@claude can you investigate this first

[claude]

Claude finished @jxnl's task —— View job • claude/issue-1612-20250618_163108 • Create PR ➔

---

✅ Fixed Exception Import Issue

The issue has been resolved! All the mentioned exceptions are now properly accessible for import.

Problem

The exceptions (ValidationError, ClientError, ConfigurationError, InstructorError, ModeError, ProviderError) existed in instructor/exceptions.py but were not exposed in the package's public API through instructor/__init__.py.

Solution

✅ Added imports to instructor/__init__.py:

from .exceptions import (
    InstructorError,
    ValidationError,
    ProviderError,
    ConfigurationError,
    ModeError,
    ClientError,
)

✅ Added exceptions to __all__ list to expose them in the public API

Result

Users can now import exceptions successfully:

# From exceptions module (what was failing before)
from instructor.exceptions import ValidationError, ClientError

# Or from main instructor module  
from instructor import ValidationError, ClientError

Changes Made

• Modified instructor/__init__.py to import and export all exception classes
• Committed fix with proper conventional commit message
• References issue Cannot import instructor.exceptions. ClientError,ConfigurationError,InstructorError,ModeError,ProviderError,ValidationError #1612

---

[MonsignorEduardo]

The issue is that the docs are referencing the main branch instead of the latest released version.
If install from main branch the error should disapear.
The fix is that the docs should be pinned to the lastest released tag not the main branch. Or allow to select the version like pydantic does

[ivanleomk]

It seems like this was added to main in this commit (cc67955) which was after we had cut the new release branch for 1.8.3.

I'll push out a new version soon which has this included, thanks for flagging this out @MonsignorEduardo .