Skip to main content
All NoteWise exceptions are defined in notewise/errors.py. Every exception inherits from NoteWiseError and may carry structured context as keyword arguments accessible via the .context property. When a video fails, format_user_error() converts the exception into a plain-English message suitable for display in the CLI or the --no-ui output stream. This message is also stored in the error field of the VIDEO_FAILED pipeline event. Exit codes: NoteWise exits with 0 on full success and 1 on any failure.

​
Exception hierarchy

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

​
Base exception

​
NoteWiseError

The root base class for all NoteWise application exceptions. Context fields: Arbitrary keyword arguments passed at raise time, accessible via .context.

​
Configuration and validation errors

​
ConfigurationError

Cause: Invalid or missing configuration at startup — for example, a TEMPERATURE value outside 0.0–1.0, a MAX_TOKENS value that is not a positive integer, or a required field that is absent when the selected model demands it. What to do: Run notewise config to display the current configuration and identify the invalid field. Run notewise setup or notewise edit-config to correct the value.

​
ValidationError

Cause: Invalid user input passed to a CLI command — a malformed YouTube URL, an unrecognised file path, or an option value that fails validation before processing starts. What to do: Check the error message for the specific field. Re-read the notewise process --help output to confirm the expected format.

​
UserVisibleCliError

Cause: A structured CLI failure that has a human-readable title, an optional introductory sentence, and a list of (label, detail) rows. Used when the error state has multiple facets worth displaying in a formatted table rather than a plain message. What to do: The CLI renders this error as a formatted panel. Read each row for actionable detail. Fields:
  • title — Short description of what went wrong.
  • intro — Optional introductory sentence (may be None).
  • rows — List of (label, detail) tuples rendered as a two-column table.

​
YouTube errors

​
YouTubeError

Base class for all YouTube-related errors. Catch this if you need to handle any YouTube failure without distinguishing the specific subtype.

​
VideoUnavailableError

Cause: The video or playlist requires authentication or is restricted. NoteWise raises this with a reason context field set to one of:
ReasonTrigger
privateVideo is marked private on YouTube
members_onlyVideo is restricted to channel members
age_restrictedVideo requires age confirmation
login_requiredContent requires a signed-in account
unavailableVideo is deleted, removed, or the ID does not exist
What to do:
  • For private, members_only, age_restricted, or login_required: export a Netscape cookie file from a browser session that has access and pass it with --cookie-file (or set YOUTUBE_COOKIE_FILE in config.env).
  • For unavailable: verify the video ID is correct and the video is still public.

​
TranscriptUnavailableError

Cause: No usable transcript track could be found or fetched for the video. Common causes include: the video creator has disabled captions, captions exist only in an unsupported language, or the caption data could not be fetched after retries. What to do:
  • Try passing -l / --language with a different language code (e.g., --language en, --language es).
  • Check on YouTube directly that the video has closed captions or auto-generated captions enabled.
  • If the video genuinely has no captions, NoteWise cannot process it.

​
IPBlockError

Cause: YouTube is actively blocking requests from the current network. Typically triggered by too many rapid requests from a shared IP address (datacenter, VPN, or corporate network). What to do:
  • Wait and retry later.
  • Lower YOUTUBE_REQUESTS_PER_MINUTE in config.env.
  • Switch to a different network or disable a VPN.

​
PlaylistError

Cause: A playlist URL could not be resolved or expanded — the playlist may be private, deleted, or the URL is malformed. What to do:
  • Confirm the playlist is public and the URL is correct.
  • For private playlists, provide --cookie-file from an account that has access.

​
ExtractionError

Cause: A low-level failure in YouTube’s HTML parsing or innertube API response. Usually indicates a YouTube API change or a network interruption mid-request. What to do:
  • Retry the command — transient network issues often resolve themselves.
  • Check whether NoteWise has a pending update with notewise update, as YouTube API changes may require a new release.

​
LLM errors

​
LLMError

Base class for all LLM provider errors. Catch this to handle any LLM failure generically.

​
LLMGenerationError

Cause: The configured LLM provider returned an error response or an empty result. Common causes include:
  • Invalid or expired API key
  • Model rate limit exceeded (HTTP 429)
  • Requested model does not exist or is unavailable for the account
  • Network timeout connecting to the provider
What to do:
  • Verify the API key with notewise config (keys are masked but presence is shown).
  • Check your provider’s dashboard for quota or billing issues.
  • Retry after a short wait if the error looks transient (rate limit or timeout).
  • Try a different model with --model to isolate whether the issue is provider-specific.

​
Persistence errors

​
PersistenceError

Cause: An SQLite database operation failed. Possible causes include: the state directory is not writable, the cache database file is corrupted, or disk space is exhausted. What to do:
  • Check that ~/.notewise/ (or your NOTEWISE_HOME path) exists and is writable.
  • Run notewise doctor to diagnose cache health.
  • If the database is corrupted, run notewise cache clear to reset it (this does not affect generated output files).

​
Update errors

​
UpdateError

Cause: Checking for a new NoteWise release failed — typically a network timeout or the GitHub releases API being temporarily unreachable. What to do:
  • Retry notewise update when your network connection is stable.
  • Check the GitHub releases page manually if the problem persists.

​
format_user_error()

format_user_error(error) converts any exception into a single plain-English string safe to display to end users. It handles the following patterns:
Pattern matchedMessage returned
VideoUnavailableErrorReason-specific message from the exception string
IPBlockErrorRate-limit / network-switch advice
TranscriptUnavailableErrorCaption availability advice
Timeout keywords”The request timed out…”
Network keywords (connection reset, etc.)”A network problem interrupted processing…”
Rate-limit keywords (429, too many requests)“The upstream service is rate-limiting…”
Auth keywords (api key, unauthorized, etc.)”The selected model or provider is not configured correctly…”
Permission denied”NoteWise could not write the output files…”
Anything else”We couldn’t process this video. Check the current session log…”
The session log path is printed by notewise logs and contains structured log entries with full tracebacks for technical debugging.

Build docs developers (and LLMs) love

Get started for freeTalk to us