1# NotebookLM Skill Troubleshooting Guide
2 
3## Quick Fix Table
4 
5| Error | Solution |
6|-------|----------|
7| ModuleNotFoundError | Use `python scripts/run.py [script].py` |
8| Authentication failed | Browser must be visible for setup |
9| Browser crash | `python scripts/run.py cleanup_manager.py --preserve-library` |
10| Rate limit hit | Wait 1 hour or switch accounts |
11| Notebook not found | `python scripts/run.py notebook_manager.py list` |
12| Script not working | Always use run.py wrapper |
13 
14## Critical: Always Use run.py
15 
16Most issues are solved by using the run.py wrapper:
17 
18```bash
19# ✅ CORRECT - Always:
20python scripts/run.py auth_manager.py status
21python scripts/run.py ask_question.py --question "..."
22 
23# ❌ WRONG - Never:
24python scripts/auth_manager.py status  # ModuleNotFoundError!
25```
26 
27## Common Issues and Solutions
28 
29### Authentication Issues
30 
31#### Not authenticated error
32```
33Error: Not authenticated. Please run auth setup first.
34```
35 
36**Solution:**
37```bash
38# Check status
39python scripts/run.py auth_manager.py status
40 
41# Setup authentication (browser MUST be visible!)
42python scripts/run.py auth_manager.py setup
43# User must manually log in to Google
44 
45# If setup fails, try re-authentication
46python scripts/run.py auth_manager.py reauth
47```
48 
49#### Authentication expires frequently
50**Solution:**
51```bash
52# Clear old authentication
53python scripts/run.py cleanup_manager.py --preserve-library
54 
55# Fresh authentication setup
56python scripts/run.py auth_manager.py setup --timeout 15
57 
58# Use persistent browser profile
59export PERSIST_AUTH=true
60```
61 
62#### Google blocks automated login
63**Solution:**
641. Use dedicated Google account for automation
652. Enable "Less secure app access" if available
663. ALWAYS use visible browser:
67```bash
68python scripts/run.py auth_manager.py setup
69# Browser MUST be visible - user logs in manually
70# NO headless parameter exists - use --show-browser for debugging
71```
72 
73### Browser Issues
74 
75#### Browser crashes or hangs
76```
77TimeoutError: Waiting for selector failed
78```
79 
80**Solution:**
81```bash
82# Kill hanging processes
83pkill -f chromium
84pkill -f chrome
85 
86# Clean browser state
87python scripts/run.py cleanup_manager.py --confirm --preserve-library
88 
89# Re-authenticate
90python scripts/run.py auth_manager.py reauth
91```
92 
93#### Browser not found error
94**Solution:**
95```bash
96# Install Chromium via run.py (automatic)
97python scripts/run.py auth_manager.py status
98# run.py will install Chromium automatically
99 
100# Or manual install if needed
101cd ~/.claude/skills/notebooklm
102source .venv/bin/activate
103python -m patchright install chromium
104```
105 
106### Rate Limiting
107 
108#### Rate limit exceeded (50 queries/day)
109**Solutions:**
110 
111**Option 1: Wait**
112```bash
113# Check when limit resets (usually midnight PST)
114date -d "tomorrow 00:00 PST"
115```
116 
117**Option 2: Switch accounts**
118```bash
119# Clear current auth
120python scripts/run.py auth_manager.py clear
121 
122# Login with different account
123python scripts/run.py auth_manager.py setup
124```
125 
126**Option 3: Rotate accounts**
127```python
128# Use multiple accounts
129accounts = ["account1", "account2"]
130for account in accounts:
131    # Switch account on rate limit
132    subprocess.run(["python", "scripts/run.py", "auth_manager.py", "reauth"])
133```
134 
135### Notebook Access Issues
136 
137#### Notebook not found
138**Solution:**
139```bash
140# List all notebooks
141python scripts/run.py notebook_manager.py list
142 
143# Search for notebook
144python scripts/run.py notebook_manager.py search --query "keyword"
145 
146# Add notebook if missing
147python scripts/run.py notebook_manager.py add \
148  --url "https://notebooklm.google.com/..." \
149  --name "Name" \
150  --topics "topics"
151```
152 
153#### Access denied to notebook
154**Solution:**
1551. Check if notebook is still shared publicly
1562. Re-add notebook with updated URL
1573. Verify correct Google account is used
158 
159#### Wrong notebook being used
160**Solution:**
161```bash
162# Check active notebook
163python scripts/run.py notebook_manager.py list | grep "active"
164 
165# Activate correct notebook
166python scripts/run.py notebook_manager.py activate --id correct-id
167```
168 
169### Virtual Environment Issues
170 
171#### ModuleNotFoundError
172```
173ModuleNotFoundError: No module named 'patchright'
174```
175 
176**Solution:**
177```bash
178# ALWAYS use run.py - it handles venv automatically!
179python scripts/run.py [any_script].py
180 
181# run.py will:
182# 1. Create .venv if missing
183# 2. Install dependencies
184# 3. Run the script
185```
186 
187#### Wrong Python version
188**Solution:**
189```bash
190# Check Python version (needs 3.8+)
191python --version
192 
193# If wrong version, specify correct Python
194python3.8 scripts/run.py auth_manager.py status
195```
196 
197### Network Issues
198 
199#### Connection timeouts
200**Solution:**
201```bash
202# Increase timeout
203export TIMEOUT_SECONDS=60
204 
205# Check connectivity
206ping notebooklm.google.com
207 
208# Use proxy if needed
209export HTTP_PROXY=http://proxy:port
210export HTTPS_PROXY=http://proxy:port
211```
212 
213### Data Issues
214 
215#### Corrupted notebook library
216```
217JSON decode error when listing notebooks
218```
219 
220**Solution:**
221```bash
222# Backup current library
223cp ~/.claude/skills/notebooklm/data/library.json library.backup.json
224 
225# Reset library
226rm ~/.claude/skills/notebooklm/data/library.json
227 
228# Re-add notebooks
229python scripts/run.py notebook_manager.py add --url ... --name ...
230```
231 
232#### Disk space full
233**Solution:**
234```bash
235# Check disk usage
236df -h ~/.claude/skills/notebooklm/data/
237 
238# Clean up
239python scripts/run.py cleanup_manager.py --confirm --preserve-library
240```
241 
242## Debugging Techniques
243 
244### Enable verbose logging
245```bash
246export DEBUG=true
247export LOG_LEVEL=DEBUG
248python scripts/run.py ask_question.py --question "Test" --show-browser
249```
250 
251### Test individual components
252```bash
253# Test authentication
254python scripts/run.py auth_manager.py status
255 
256# Test notebook access
257python scripts/run.py notebook_manager.py list
258 
259# Test browser launch
260python scripts/run.py ask_question.py --question "test" --show-browser
261```
262 
263### Save screenshots on error
264Add to scripts for debugging:
265```python
266try:
267    # Your code
268except Exception as e:
269    page.screenshot(path=f"error_{timestamp}.png")
270    raise e
271```
272 
273## Recovery Procedures
274 
275### Complete reset
276```bash
277#!/bin/bash
278# Kill processes
279pkill -f chromium
280 
281# Backup library if exists
282if [ -f ~/.claude/skills/notebooklm/data/library.json ]; then
283    cp ~/.claude/skills/notebooklm/data/library.json ~/library.backup.json
284fi
285 
286# Clean everything
287cd ~/.claude/skills/notebooklm
288python scripts/run.py cleanup_manager.py --confirm --force
289 
290# Remove venv
291rm -rf .venv
292 
293# Reinstall (run.py will handle this)
294python scripts/run.py auth_manager.py setup
295 
296# Restore library if backup exists
297if [ -f ~/library.backup.json ]; then
298    mkdir -p ~/.claude/skills/notebooklm/data/
299    cp ~/library.backup.json ~/.claude/skills/notebooklm/data/library.json
300fi
301```
302 
303### Partial recovery (keep data)
304```bash
305# Keep auth and library, fix execution
306cd ~/.claude/skills/notebooklm
307rm -rf .venv
308 
309# run.py will recreate venv automatically
310python scripts/run.py auth_manager.py status
311```
312 
313## Error Messages Reference
314 
315### Authentication Errors
316| Error | Cause | Solution |
317|-------|-------|----------|
318| Not authenticated | No valid auth | `run.py auth_manager.py setup` |
319| Authentication expired | Session old | `run.py auth_manager.py reauth` |
320| Invalid credentials | Wrong account | Check Google account |
321| 2FA required | Security challenge | Complete in visible browser |
322 
323### Browser Errors
324| Error | Cause | Solution |
325|-------|-------|----------|
326| Browser not found | Chromium missing | Use run.py (auto-installs) |
327| Connection refused | Browser crashed | Kill processes, restart |
328| Timeout waiting | Page slow | Increase timeout |
329| Context closed | Browser terminated | Check logs for crashes |
330 
331### Notebook Errors
332| Error | Cause | Solution |
333|-------|-------|----------|
334| Notebook not found | Invalid ID | `run.py notebook_manager.py list` |
335| Access denied | Not shared | Re-share in NotebookLM |
336| Invalid URL | Wrong format | Use full NotebookLM URL |
337| No active notebook | None selected | `run.py notebook_manager.py activate` |
338 
339## Prevention Tips
340 
3411. **Always use run.py** - Prevents 90% of issues
3422. **Regular maintenance** - Clear browser state weekly
3433. **Monitor queries** - Track daily count to avoid limits
3444. **Backup library** - Export notebook list regularly
3455. **Use dedicated account** - Separate Google account for automation
346 
347## Getting Help
348 
349### Diagnostic information to collect
350```bash
351# System info
352python --version
353cd ~/.claude/skills/notebooklm
354ls -la
355 
356# Skill status
357python scripts/run.py auth_manager.py status
358python scripts/run.py notebook_manager.py list | head -5
359 
360# Check data directory
361ls -la ~/.claude/skills/notebooklm/data/
362```
363 
364### Common questions
365 
366**Q: Why doesn't this work in Claude web UI?**
367A: Web UI has no network access. Use local Claude Code.
368 
369**Q: Can I use multiple Google accounts?**
370A: Yes, use `run.py auth_manager.py reauth` to switch.
371 
372**Q: How to increase rate limit?**
373A: Use multiple accounts or upgrade to Google Workspace.
374 
375**Q: Is this safe for my Google account?**
376A: Use dedicated account for automation. Only accesses NotebookLM.