Skip to main content
This page covers the most common problems you may encounter when running NoteWise. For each issue, the error message shown in the terminal is included alongside the recommended fix.

​
Run a health check first

Before diving into specific errors, run notewise doctor to check whether your config, API key, output directory, and cache database are all healthy: 
notewise doctor
Each check is reported as OK, WARN, or FAIL. Fix any FAIL items before proceeding.

​
Check the session log

Many errors include more detail in the structured session log. Tail the latest log after a failed run: 
notewise logs --tail 50
The log records the exact exception, traceback, and contextual fields (video ID, model, etc.) that are omitted from the terminal output.

​
Common issues

Error message:
We couldn't get a usable transcript for this video. Make sure captions are
available, try another language, or use a different video.
Cause: The video does not have captions enabled, or no transcript track is available in the requested language.Fix:
  • Use notewise info "URL" to see which subtitle and auto-caption languages are available for the video.
  • Pass one or more available languages with --language: 
    notewise process "URL" --language es --language en
  • If the video has no captions at all, there is no transcript to extract. Choose a different video or request that the creator enable captions.
Error messages:
This YouTube content is private. Retry with --cookie-file / --cookies from an
account that can view it, or make it unlisted or public.

This YouTube content is members-only. Retry with --cookie-file / --cookies from
an account that has access, or use a public or unlisted alternative.

This YouTube content is age-restricted. Retry with --cookie-file / --cookies
from an eligible account, or use a public or unrestricted alternative.

This YouTube content requires sign-in. Retry with --cookie-file / --cookies,
or use a public or unlisted video.
Cause: The video requires a signed-in YouTube session (private, members-only, age-gated, or login-required).Fix: Export a Netscape-format cookie file from a browser where you are signed in to an account with access, then pass it with --cookie-file:
notewise process "URL" --cookie-file ~/cookies.txt
See Private and restricted videos for full instructions.
Error message:
YouTube is temporarily blocking requests from this network. Try again later,
lower the request rate, or switch networks.
Cause: YouTube has temporarily throttled or blocked requests from your IP address. This typically happens after many rapid requests in a short time, or when running NoteWise from a cloud/datacenter IP that YouTube treats as suspicious.Fix:
  • Wait 15–30 minutes and try again.
  • Reduce the request rate in ~/.notewise/config.env: 
    YOUTUBE_REQUESTS_PER_MINUTE=5
  • Switch to a different network or use a residential IP.
  • For large batch runs, lower MAX_CONCURRENT_VIDEOS to reduce parallel load: 
    MAX_CONCURRENT_VIDEOS=2
Error message:
The selected model or provider is not configured correctly. Check your API key
and try again.
Cause: The API key for the selected LLM provider is missing, invalid, or has been revoked. This can also happen if you are using a model your account does not have access to.Fix:
  • Run notewise doctor to check whether the expected API key environment variable is set.
  • Run notewise config to see the current masked configuration and verify the right key is present.
  • Re-run the setup wizard to update your key: 
    notewise setup --force
  • Verify the key is valid by testing it directly with the provider’s API or dashboard.
  • If using a non-default model, confirm your account has access to that model tier.
Error message:
The upstream service is rate-limiting requests right now. Please try again later.
Cause: Your LLM provider is returning HTTP 429 (Too Many Requests). This can happen when processing many videos in parallel with a provider that has strict per-minute or per-day quotas.Fix:
  • Wait a few minutes and retry.
  • Lower the concurrency to reduce simultaneous LLM requests: 
    MAX_CONCURRENT_VIDEOS=2
  • Check your provider’s dashboard for quota usage and limits.
  • NoteWise retries failed LLM requests automatically (up to 3 times with backoff), so transient 429s are often handled without intervention.
Error message:
The request timed out while processing this video. Please try again.
Cause: A network request to YouTube or your LLM provider timed out. This is usually transient.Fix:
  • Retry the command. Timeouts are often resolved by simply running again.
  • Check your network connection.
  • If the timeout is consistently on LLM requests for long videos, the model may be taking too long to generate a response. Try a faster model: 
    notewise process "URL" --model gemini/gemini-2.5-flash
Error message:
NoteWise could not write the output files. Check the output folder permissions
and try again.
Cause: NoteWise does not have write permission to the output directory.Fix:
  • Check the permissions on your output directory: 
    ls -la ./output
  • Grant write access: 
    chmod u+w ./output
  • Or specify a different output directory where you have write access: 
    notewise process "URL" --output ~/my-notes
  • When running in Docker, ensure the mounted host directory is writable by uid 1001 (the container’s user). See Running with Docker for details.

​
Getting more information

If none of the above resolves your issue:
  1. Tail the session log for the full error detail: 
    notewise logs --tail 100
  2. Run notewise info "URL" to check whether the source is accessible before processing.
  3. Try with --no-ui to get plain output that is easier to redirect and share: 
    notewise process "URL" --no-ui 2>&1 | tee debug.log

​
Reporting a bug

If you believe you have found a bug, open an issue on GitHub: https://github.com/whoisjayd/notewise/issues/new/choose Include:
  • The exact command you ran (with the URL replaced if needed)
  • The error message from the terminal
  • The relevant lines from notewise logs --tail 50
  • Your Python version (python --version) and NoteWise version (notewise version)
  • The model you were using

Build docs developers (and LLMs) love

Get started for freeTalk to us