Skip to main content
All custom exceptions are defined in src/notewise/errors.py and rooted at NoteWiseError.

​
Exception Hierarchy

​
Exception Details

ExceptionCauseResolution
ConfigurationErrorAPI key for selected model not setRun notewise config or notewise setup --force
ValidationErrorMalformed URL or invalid optionCheck URL format and try again
VideoUnavailableErrorVideo is private, age-restricted, or removedUse --cookie-file or verify video is public
TranscriptUnavailableErrorNo transcript available in requested languageRun notewise info "URL" to check available languages
PlaylistErrorPlaylist unavailable or invalid IDVerify playlist is public and ID is correct
IPBlockErrorYouTube blocked the requestReduce YOUTUBE_REQUESTS_PER_MINUTE and retry
ExtractionErrorGeneral YouTube extraction failureRun notewise logs --tail 50 for details
LLMGenerationErrorLLM API call failed after retriesVerify API key and quota with notewise config
PersistenceErrorSQLite read/write failureRun notewise doctor, or clear cache with notewise cache --clear --yes

​
Quick Triage

SymptomStart Here
Auth / private access failuresVideoUnavailableError — use --cookie-file
No captions availableTranscriptUnavailableError — try --language en
LLM call failuresLLMGenerationError — check API key and quota
Unexpected errorRun notewise logs --tail 100 for full details
See Private Videos for cookie file instructions.

​
CLI Error Handling

The process command maps exceptions to user-visible failure panels. Exit code is 1 when any video fails. 
notewise logs --tail 100   # full error detail

​
Exception details

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']"
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
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.
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
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.
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.
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.
Raised when YouTube detects unusual traffic and blocks the request.Resolution: Reduce YOUTUBE_REQUESTS_PER_MINUTE in your config and retry later.
General YouTube extraction failure not covered by the more specific subclasses.Resolution:
notewise logs --tail 50   # inspect the session log for detail
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.
Raised when SQLite read/write operations fail.Resolution: Run notewise doctor to check cache database health. If corrupted, clear with notewise cache --clear --yes.

​
Quick triage by symptom

Auth / private access failures

Start with VideoUnavailableError and PlaylistError. For signed-in resources, provide --cookie-file and retry. See Private Videos.

No captions or language mismatch

Start with TranscriptUnavailableError:
notewise info "URL"
notewise process "URL" --language en

LLM call failures

Check LLMGenerationError: validate API key, quota, and model access for the configured provider with notewise config.

Unexpected failure

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. Exit code is 1 when any video fails. 
notewise logs --tail 100   # full error detail
Last modified on March 28, 2026