Skip to main content

​
Quick triage

Run these three commands first — they cover 90% of issues: 
notewise doctor
notewise config
notewise logs --tail 80

​
Common failure modes

Missing or wrong API key

Symptoms: Process fails early with provider authentication errors. doctor reports a missing key.Fix:
notewise config
notewise setup --force
Key → model mapping:
Model prefixRequired key
gpt-*OPENAI_API_KEY
claude-*ANTHROPIC_API_KEY
gemini/*GEMINI_API_KEY
groq/GROQ_API_KEY
Symptoms: Video fails with transcript-unavailable messages.Fix:
notewise info "URL"                 # see available transcript languages
notewise process "URL" -l en
notewise process "URL" -l hi -l en  # fallback chain
If captions are disabled by the creator, use another video.
Symptoms: Errors mention sign-in, private content, or age restrictions.Fix:
notewise process "URL" --cookie-file ./youtube-cookies.txt
See Private Videos for cookie export instructions.
Symptoms: Errors mention rate limiting, unusual traffic, or temporary blocks.Fix: Lower concurrency and retry later:
# ~/.notewise/config.env
MAX_CONCURRENT_VIDEOS=2
YOUTUBE_REQUESTS_PER_MINUTE=5
Symptoms: Process fails near completion with file write errors.Fix:
notewise process "URL" --output ./output
Ensure the target directory is writable by your user.
Symptoms: High cost or long generation times in notewise stats.Fix: Switch to a faster/cheaper model:
notewise process "URL" --model gemini/gemini-2.5-flash

​
Debug workflow for a failing URL

1

Inspect the source

notewise info "URL"
2

Re-run in plain output mode

notewise process "URL" --no-ui
3

Read the latest logs

notewise logs --tail 120
4

Force a clean re-run if needed

notewise process "URL" --force

​
Cache issues

Only clear the cache when local metadata appears stale or corrupted: 
notewise cache --info
notewise cache --clear --yes
For routine cleanup, prefer pruning: 
notewise cache --prune 30

​
Related references

Error reference

Exception hierarchy with causes and resolution steps.

Cache & Logs guide

Full cache management and log inspection commands.