Skip to main content
This reference maps each custom exception to its likely cause and the fastest recovery action.
All custom exceptions are defined in src/notewise/errors.py and rooted at NoteWiseError.

​
Exception hierarchy

NoteWiseError
├── ConfigurationError
├── ValidationError
├── UserVisibleCliError
├── YouTubeError
│   ├── VideoUnavailableError
│   ├── TranscriptUnavailableError
│   ├── PlaylistError
│   ├── IPBlockError
│   └── ExtractionError
├── LLMError
│   └── LLMGenerationError
└── PersistenceError

​
Exception details

​
NoteWiseError

Base class for all NoteWise exceptions. Accepts a message and optional keyword context arguments appended to str(error). 
raise NoteWiseError("something went wrong", video_id="abc123")
# "something went wrong [video_id='abc123']"

​
ConfigurationError

Raised when the application configuration is invalid or required settings are missing. Cause: The API key for the selected model is not set. Resolution: 
notewise config          # see current resolved settings
notewise setup --force   # re-run the wizard
If model routing changed recently, verify both DEFAULT_MODEL and the matching provider key are present in resolved config.

​
ValidationError

Raised for invalid user input — malformed YouTube URLs, bad option values, or missing required arguments. Resolution: Check the URL or option value and try again.

​
UserVisibleCliError

A structured CLI failure rendered as a Rich panel without a traceback. Contains:
  • title — the panel heading
  • rows — list of (label, value) tuples
  • intro — optional introductory text
Used internally to present friendly error messages for expected failure modes.

​
YouTubeError and subclasses

​
VideoUnavailableError

Raised when a video requires sign-in, is private, age-restricted, or has been removed. Resolution: Supply a --cookie-file for sign-in-required content, or verify the video is publicly accessible. See Private Videos.

​
TranscriptUnavailableError

Raised when no transcript is available in any of the requested languages. Resolution: 
notewise info "URL"                  # see available transcript languages
notewise process "URL" --language en
If captions are disabled by the creator, use a different video.

​
PlaylistError

Raised when a playlist cannot be fetched or enumerated (private playlist, invalid ID). Resolution: Verify the playlist is public and the ID is correct. For private playlists, supply a --cookie-file.

​
IPBlockError

Raised when YouTube detects unusual traffic and blocks the request. Resolution: Reduce YOUTUBE_REQUESTS_PER_MINUTE in your config and retry later.

​
ExtractionError

General YouTube extraction failure not covered by the more specific subclasses. Resolution: 
notewise logs --tail 50   # inspect the session log for detail

​
LLMGenerationError

Raised when the LLM API call fails after all retries are exhausted (LLM_NUM_RETRIES = 3). Includes a redacted summary of the underlying API error. Resolution: 
notewise config   # verify the API key is set and correct
Check your API key validity and quota with the provider.

​
PersistenceError

Raised when SQLite read/write operations fail. Resolution: Run notewise doctor to check cache database health. If the database is corrupted, clear and rebuild it with notewise cache --clear --yes.

​
Quick triage by symptom

Start with VideoUnavailableError and PlaylistError. For signed-in resources, provide --cookie-file and retry. See Private Videos.
Start with TranscriptUnavailableError:
notewise info "URL"
notewise process "URL" --language en
Check LLMGenerationError: validate API key, quota, and model access for the configured provider with notewise config.
notewise logs --tail 100
The session log includes the full exception with context.

​
CLI error handling

The process command maps exceptions to user-visible failure panels. Unhandled exceptions are logged to the session log file and a truncated error panel pointing to the log is shown. The exit code is 1 when any video fails. 
notewise logs --tail 100   # full error detail