Troubleshooting

This guide covers common problems you might encounter when setting up and using Morning Brain Starter.

Setup Issues

Python not found or wrong version

Symptoms:

python: command not found
Python version is 2.x when you need 3.x
Scripts fail with syntax errors

Solutions:Try python3 instead of python:

python3 --version
python3 -m venv .venv

Install Python 3.8+ if missing:

# macOS with Homebrew
brew install python3

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-venv python3-pip

# Check version
python3 --version  # Should be 3.8 or higher

Update your shell aliases (add to .bashrc or .zshrc):

alias python=python3
alias pip=pip3

Virtual environment activation fails

Symptoms:

source .venv/bin/activate does nothing
Commands still use system Python
Package installations go to wrong location

Solutions:Recreate the virtual environment:

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows, use different activation:

# Command Prompt
.venv\Scripts\activate.bat

# PowerShell
.venv\Scripts\Activate.ps1

Verify activation worked:

which python  # Should show .venv/bin/python
python --version

Missing dependencies or import errors

Symptoms:

ModuleNotFoundError: No module named 'google'
ImportError: cannot import name 'build'
Scripts fail with import errors

Solutions:Ensure virtual environment is activated:

source .venv/bin/activate

Install/reinstall dependencies:

pip install --upgrade pip
pip install -r requirements.txt

Check for conflicting installations:

pip list | grep google
pip uninstall google-api-python-client
pip install google-api-python-client

If still failing, clear pip cache:

pip cache purge
pip install -r requirements.txt --no-cache-dir

OAuth and Authentication

OAuth browser window doesn't open

Symptoms:

setup_oauth.py runs but no browser window appears
Script hangs waiting for authorization
Port binding errors

Solutions:Check for port conflicts:

# Kill process using the OAuth callback port
lsof -ti:8080 | xargs kill -9

Try manual OAuth flow:

# The script will print a URL - copy and paste into browser manually
.venv/bin/python scripts/setup_oauth.py --regenerate

Check firewall settings:

Allow Python to accept incoming connections
Allow localhost connections on ephemeral ports
Temporarily disable firewall for testing

If on remote server, use port forwarding:

ssh -L 8080:localhost:8080 user@server

Invalid client_id or client_secret

Symptoms:

Error: invalid_client
Falta GOOGLE_CLIENT_ID o GOOGLE_CLIENT_SECRET
OAuth flow fails immediately

Solutions:Verify .env file exists and has correct values:

# Check file location
ls -la resources/secrets/.env

# View contents (be careful - sensitive data!)
cat resources/secrets/.env

Expected format:

GOOGLE_CLIENT_ID=123456789-abcdefg.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abcdefg123456
GOOGLE_REFRESH_TOKEN=1//abc...

Get correct credentials from Google Cloud Console:

Go to console.cloud.google.com
Navigate to APIs & Services > Credentials
Find your OAuth 2.0 Client ID
Download JSON and extract client_id and client_secret

Regenerate credentials if compromised:

Delete old OAuth client in Google Cloud Console
Create new OAuth 2.0 Client ID
Update .env with new values
Run setup_oauth.py --regenerate

Refresh token invalid or expired

Symptoms:

Error: invalid_grant
“Token has been expired or revoked”
API calls fail with 401 Unauthorized

Solutions:Regenerate the refresh token:

.venv/bin/python scripts/setup_oauth.py --regenerate

This will:

Open OAuth flow in browser
Generate new refresh token
Update GOOGLE_REFRESH_TOKEN in .env

Common causes:

Token manually revoked in Google account settings
OAuth consent screen moved from Testing to Production
Client secret was regenerated
More than 50 refresh tokens issued (older ones expire)

Prevent future issues:

Don’t share .env file
Don’t commit refresh tokens to git
Keep OAuth consent screen in Testing for personal use

Permission and Scope Issues

Missing required scopes

Symptoms:

Error: Insufficient Permission
“Request had insufficient authentication scopes”
Features work partially but some fail

Solutions:Check required scopes in scripts/setup_oauth.py:

GOOGLE_SCOPES = [
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/calendar.events",
    "https://www.googleapis.com/auth/meetings.space.settings",
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/documents.readonly",
]

Regenerate token with all scopes:

.venv/bin/python scripts/setup_oauth.py --regenerate

Verify scopes in OAuth consent screen:

Go to Google Cloud Console
APIs & Services > OAuth consent screen
Check that all scopes are listed
Add any missing scopes
Regenerate token

Feature-specific scope requirements:

Calendar read: calendar.readonly
Accept/decline events: calendar.events
Meet transcription: meetings.space.settings
Gmail: gmail.readonly
Read transcripts: documents.readonly

API not enabled in Google Cloud

Symptoms:

Error: API not enabled
“Google Calendar API has not been used”
403 Forbidden errors

Solutions:Enable required APIs in Google Cloud Console:

Google Calendar API:
- Go to console.cloud.google.com
- APIs & Services > Library
- Search “Google Calendar API”
- Click Enable
Google Meet API (for transcription):
- APIs & Services > Library
- Search “Google Meet API”
- Click Enable
Gmail API:
- Search “Gmail API”
- Click Enable
Google Docs API (for transcripts):
- Search “Google Docs API”
- Click Enable

Verify APIs are enabled:

# List enabled APIs
gcloud services list --enabled

Common mistake: Enabling APIs in wrong project

Ensure you’re in the same project as your OAuth credentials
Check project ID matches in Console and .env

Rate limiting or quota exceeded

Symptoms:

Error: Rate Limit Exceeded
“Quota exceeded for quota metric”
Intermittent API failures

Solutions:Check your quota usage:

Google Cloud Console
APIs & Services > Dashboard
View API metrics

Increase quotas if needed:

APIs & Services > Quotas
Find the relevant API and metric
Request quota increase (may require billing)

Reduce API calls:

# Use demo mode for testing
touch config/demo_gmail_fake.yaml

# Fetch fewer days of data
python scripts/calendar_lite.py --range today

# Don't fetch all calendars
python scripts/email_lite.py --limit 10

Implement caching:

Store results locally
Only fetch new data since last run
Use incremental sync where available

Configuration Issues

Configuration files not found

Symptoms:

FileNotFoundError: config/clients.yaml
Scripts can’t find config files
Features don’t work as expected

Solutions:Check working directory:

# Run scripts from project root
cd /path/to/morning-brain-starter
.venv/bin/python scripts/calendar_lite.py

Create missing config files:

# Copy examples if they exist
cp config/clients.yaml.example config/clients.yaml
cp config/asana_order.yaml.example config/asana_order.yaml

Verify directory structure:

ls -la config/
# Should show: clients.yaml, asana_order.yaml, calendar.yaml, etc.

Check file permissions:

chmod 644 config/*.yaml

YAML syntax errors

Symptoms:

yaml.scanner.ScannerError
“mapping values are not allowed here”
Config files not parsed correctly

Solutions:Validate YAML syntax:

# Install yamllint
pip install yamllint

# Check syntax
yamllint config/clients.yaml

Common YAML mistakes:

# ❌ Wrong - missing space after colon
clients:
  tycho:- tycho

# ✅ Correct
clients:
  tycho:
    - tycho

# ❌ Wrong - inconsistent indentation
clients:
  tycho:
   - tycho  # 1 space
    - station  # 2 spaces

# ✅ Correct - consistent 2-space indentation
clients:
  tycho:
    - tycho
    - station

Use a YAML validator online:

Copy file contents
Paste into yamllint.com
Fix reported errors

Client or project not matching

Symptoms:

Events not appearing in client bitácoras
Emails not assigned to correct client
Projects showing as “Unknown”

Solutions:Check keyword matching in config/clients.yaml:

clients:
  tycho:
    - tycho        # Matches "Tycho", "tycho station", etc.
    - station      # More keywords = more matches

Test matching manually:

# Print client assignments
python scripts/calendar_lite.py --today --match-clients

Common issues:

Keywords are case-sensitive in some contexts (use lowercase)
Need to match substring of event title or email subject
Client folder name must match key in YAML

Verify directory structure matches config:

# Config says "tycho"
ls context/clients/tycho  # Must exist with this exact name

Runtime Errors

Morning routine fails partway through

Symptoms:

Script starts but crashes mid-execution
Partial output then error
Some features work, others don’t

Solutions:Run components individually to isolate issue:

# Test calendar
.venv/bin/python scripts/calendar_lite.py --today

# Test email
.venv/bin/python scripts/email_lite.py --list

# Test Asana
.venv/bin/python scripts/asana_lite.py --today

Check logs for specific error:

# Run with verbose output
.venv/bin/python run_morning.py 2>&1 | tee morning.log

Common causes:

One API is down (skip and continue)
Rate limit hit (wait and retry)
Config file issue (check YAML syntax)
Missing dependencies (reinstall requirements)

Create fallback configuration:

# Use demo mode for problematic API
touch config/demo_gmail_fake.yaml

Transcription features not working

Symptoms:

--add-transcription-reminder does nothing
No transcripts imported
Meet API errors

Solutions:Verify Meet API setup:

# Check if scope is available
.venv/bin/python -c "import os; from scripts.credentials import load_env; load_env(); print(os.getenv('GOOGLE_REFRESH_TOKEN')[:20])"

Ensure APIs are enabled:

Google Meet API
Google Docs API

Regenerate token with all scopes:

.venv/bin/python scripts/setup_oauth.py --regenerate

Test transcription import:

# Try to import yesterday's transcripts
python scripts/calendar_lite.py --import-transcriptions

If no transcripts found:

Verify meeting actually generated a transcript
Check transcript is attached to calendar event
Ensure event matches a client in clients.yaml

See detailed guide: Meet Transcriptions

Bitácoras not updating

Symptoms:

New meetings/emails don’t appear in bitácoras
Bitácora files empty or outdated
Client logs not being created

Solutions:Run bitácora update manually:

.venv/bin/python scripts/bitacora_append.py

Check client configuration:

# Verify clients.yaml exists and is valid
cat config/clients.yaml

# Verify client directories exist
ls -la context/clients/

Test client matching:

# See which events match which clients
python scripts/calendar_lite.py --today --match-clients

Common issues:

Client name in YAML doesn’t match folder name
Keywords don’t match event titles
Events already in bitácora (duplicates skipped)
File permissions prevent writing

Check file permissions:

chmod 755 context/clients/*/
chmod 644 context/clients/*/bitacora.md

See detailed guide: Client Bitácoras

Getting Help

If these solutions don’t resolve your issue:

Check the source code: All scripts include docstrings and comments
Review error messages: They often indicate exactly what’s wrong
Test with demo mode: Isolate whether issue is with APIs or local code
Check file paths: Ensure you’re running from project root directory
Verify Python version: Must be 3.8 or higher

Most issues are related to OAuth scopes, API enablement, or configuration file syntax. Double-check these areas first.

How-To Guides

Setup Issues

OAuth and Authentication

Permission and Scope Issues

Configuration Issues

Runtime Errors

Getting Help

Build docs developers (and LLMs) love

How-To Guides

​Setup Issues

​OAuth and Authentication

​Permission and Scope Issues

​Configuration Issues

​Runtime Errors

​Getting Help

Build docs developers (and LLMs) love

Setup Issues

OAuth and Authentication

Permission and Scope Issues

Configuration Issues

Runtime Errors

Getting Help