claude-skills-reference/engineering-team/google-workspace-cli/references/troubleshooting.md

Google Workspace CLI Troubleshooting

Common errors, fixes, and platform-specific guidance for the gws CLI.

---

Installation Issues

gws not found on PATH

Error: command not found: gws

Fixes:

# Check if installed
npm list -g @anthropic/gws 2>/dev/null || echo "Not installed via npm"
which gws || echo "Not on PATH"

# Install via npm
npm install -g @anthropic/gws

# If npm global bin not on PATH
export PATH="$(npm config get prefix)/bin:$PATH"
# Add to ~/.zshrc or ~/.bashrc for persistence

npm permission errors

Error: EACCES: permission denied

Fixes:

# Option 1: Fix npm prefix (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Option 2: Use npx without installing
npx @anthropic/gws --version

Cargo build failures

Error: error[E0463]: can't find crate

Fixes:

# Ensure Rust is up to date
rustup update stable

# Clean build
cargo clean && cargo install gws-cli

---

Authentication Errors

Token expired

Error: 401 Unauthorized: Token has been expired or revoked

Cause: OAuth tokens expire after 1 hour.

Fix:

gws auth refresh
# If refresh fails:
gws auth setup  # Re-authenticate

Insufficient scopes

Error: 403 Forbidden: Request had insufficient authentication scopes

Fix:

# Check current scopes
gws auth status --json | grep scopes

# Re-auth with additional scopes
gws auth setup --scopes gmail,drive,calendar,sheets,tasks

# Or list required scopes for a service
python3 scripts/auth_setup_guide.py --scopes gmail,drive

Keyring/keychain errors

Error: Failed to access keyring or SecKeychainFindGenericPassword failed

Fixes:

# macOS: Unlock keychain
security unlock-keychain ~/Library/Keychains/login.keychain-db

# Linux: Install keyring backend
sudo apt install gnome-keyring  # or libsecret

# Fallback: Use file-based token storage
export GWS_TOKEN_PATH=~/.config/gws/token.json
gws auth setup

Service account delegation errors

Error: 403: Not Authorized to access this resource/api

Fix:

1. Verify domain-wide delegation is enabled on the service account
2. Verify client ID is authorized in Admin Console > Security > API Controls
3. Verify scopes match exactly (no trailing slashes)
4. Verify GWS_DELEGATED_USER is a valid admin account

# Debug
echo $GWS_SERVICE_ACCOUNT_KEY  # Should point to valid JSON key file
echo $GWS_DELEGATED_USER       # Should be admin@yourdomain.com
gws auth status --json          # Check auth details

---

API Errors

Rate limit exceeded (429)

Error: 429 Too Many Requests: Rate Limit Exceeded

Cause: Google Workspace APIs have per-user, per-service rate limits.

Fix:

# Add delays between bulk operations
for id in $(cat file_ids.txt); do
    gws drive files get $id --json >> results.json
    sleep 0.5  # 500ms delay
done

# Use --limit to reduce result size
gws drive files list --limit 100 --json

# For admin operations, batch in groups of 50

Rate limits by service:

Service	Limit
Gmail	250 quota units/second/user
Drive	1,000 requests/100 seconds/user
Sheets	60 read requests/minute/user
Calendar	500 requests/100 seconds/user
Admin SDK	2,400 requests/minute

Permission denied (403)

Error: 403 Forbidden: The caller does not have permission

Causes and fixes:

1. Wrong scope — Re-auth with correct scopes
2. Not the file owner — Request access from the owner
3. Domain policy — Check Admin Console sharing policies
4. API not enabled — Enable the API in Google Cloud Console

# Check which APIs are enabled
gws schema --list

# Enable an API
# Go to: console.cloud.google.com > APIs & Services > Library

Not found (404)

Error: 404 Not Found: File not found

Causes:

1. File was deleted or moved to trash
2. File ID is incorrect
3. No permission to see the file

# Check trash
gws drive files list --query "trashed=true and name='filename'" --json

# Verify file ID
gws drive files get <fileId> --json

---

Output Parsing Issues

NDJSON vs JSON array

Problem: Output format varies between commands and versions.

# Force JSON array output
gws drive files list --json

# Force NDJSON output
gws drive files list --format ndjson

# Handle both in output_analyzer.py (automatic detection)
gws drive files list --json | python3 scripts/output_analyzer.py --count

Pagination

Problem: Only partial results returned.

# Fetch all pages
gws drive files list --page-all --json

# Or set a high limit
gws drive files list --limit 1000 --json

# Check if more pages exist (look for nextPageToken in output)
gws drive files list --limit 100 --json | grep nextPageToken

Empty response

Problem: Command returns empty or {}.

# Check auth
gws auth status

# Try with verbose output
gws drive files list --verbose --json

# Check if the service is accessible
gws drive about get --json

---

Platform-Specific Issues

macOS

Keychain access prompts:

# Allow gws to access keychain without repeated prompts
# In Keychain Access.app, find "gws" entries and set "Allow all applications"

# Or use file-based storage
export GWS_TOKEN_PATH=~/.config/gws/token.json

Browser not opening for OAuth:

# If default browser doesn't open
gws auth setup --no-browser
# Copy the URL manually and paste in browser

Linux

Headless OAuth (no browser):

# Use out-of-band flow
gws auth setup --no-browser
# Prints a URL — open on another machine, paste code back

# Or use service account (no browser needed)
export GWS_SERVICE_ACCOUNT_KEY=/path/to/key.json
export GWS_DELEGATED_USER=admin@domain.com

Missing keyring backend:

# Install a keyring backend
sudo apt install gnome-keyring libsecret-1-dev

# Or use file-based storage
export GWS_TOKEN_PATH=~/.config/gws/token.json

Windows

PATH issues:

# Add npm global bin to PATH
$env:PATH += ";$(npm config get prefix)\bin"

# Or use npx
npx @anthropic/gws --version

PowerShell quoting:

# Use single quotes for JSON arguments
gws gmail users.settings.filters create me `
  --criteria '{"from":"test@example.com"}' `
  --action '{"addLabelIds":["Label_1"]}'

---

Getting Help

# General help
gws --help
gws <service> --help
gws <service> <resource> --help

# API schema for a method
gws schema gmail.users.messages.send

# Version info
gws --version

# Debug mode
gws --verbose <command>

# Report issues
# https://github.com/googleworkspace/cli/issues