Common Issues

Solutions for frequently encountered problems with the Google Workspace CLI

Command Not Found

Error: gws: command not found

Cause: The CLI is not installed or not in your PATH.

Solution for npm/npx installation

If you installed via npm:

npm install -g @googleworkspace/cli

Verify installation:

which gws
gws --version

If which gws returns nothing: Your npm global bin directory is not in your PATH.

Find the npm bin path:

npm bin -g

Add it to your PATH in ~/.bashrc, ~/.zshrc, or equivalent:

export PATH="$PATH:$(npm bin -g)"

Reload your shell:

source ~/.bashrc  # or ~/.zshrc

Solution for Cargo installation

If you installed via Cargo:

cargo install --path .

Ensure ~/.cargo/bin is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Add to your shell config (~/.bashrc or ~/.zshrc) to make it permanent.

JSON Parsing Errors

Error: Failed to parse JSON

Cause: Invalid JSON syntax in --params or --json arguments.

Common JSON mistakes

Problem: Single quotes inside JSON strings

# WRONG
gws drive files list --params "{"pageSize": 5}"

Solution: Use single quotes for the shell, double quotes for JSON:

# CORRECT
gws drive files list --params '{"pageSize": 5}'

Problem: Trailing commas

# WRONG
gws drive files list --params '{"pageSize": 5,}'

Solution: Remove trailing commas:

# CORRECT
gws drive files list --params '{"pageSize": 5}'

Validate JSON before using

Use jq to validate your JSON:

echo '{"pageSize": 5}' | jq .

If jq returns formatted JSON, it’s valid.

Build complex JSON with jq:

gws sheets spreadsheets create --json "$(jq -n '{
  properties: {
    title: "Q1 Budget"
  }
}')"

Error: Missing required field

Cause: Your JSON is missing a required parameter for the API method.

Solution: Use gws schema to inspect the method’s required fields:

gws schema drive.files.create

This shows the request schema with required fields marked.

Rate Limiting

Error: 429 Too Many Requests

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'Queries' and limit 'Queries per day'"
  }
}

Cause: You’ve exceeded the API quota for your Google Cloud project.

Short-term solutions

1. Wait and retry: Most quotas reset daily or per minute
2. Use pagination delay: Add --page-delay to slow down requests:
   gws drive files list --page-all --page-delay 1000  # 1 second between pages
   
3. Reduce page size: Request fewer items per page:
   gws drive files list --params '{"pageSize": 10}'
   

Long-term solutions

Request a quota increase:

1. Go to Google Cloud Console > IAM & Admin > Quotas
2. Filter by the API service (e.g., “Gmail API”)
3. Select the quota metric you need to increase
4. Click Edit Quotas and submit a request

Enable billing: Some APIs have higher quotas for projects with billing enabled.

Network Errors

Error: Connection timeout or DNS resolution failed

Causes:

• No internet connection
• Firewall blocking Google API domains
• Proxy configuration needed

Solutions

Check connectivity:

curl https://www.googleapis.com

Configure proxy (if behind corporate firewall):

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080

Verify DNS:

nslookup www.googleapis.com

If DNS fails, check your network settings or try a different DNS server (e.g., Google DNS: 8.8.8.8).

Error: SSL certificate problem

Cause: SSL/TLS certificate verification failed.

Solution:

1. Update your system’s CA certificates:

   # Ubuntu/Debian
   sudo apt-get update && sudo apt-get install ca-certificates
   
   # macOS
   brew install ca-certificates
   

2. If behind a corporate proxy with SSL inspection, install your organization’s root CA certificate.

Discovery Document Errors

Error: Failed to fetch discovery document

Cause: Cannot retrieve the API specification from Google’s Discovery Service.

Solutions

Check network connectivity (see Network Errors above)

Clear cache: Discovery documents are cached for 24 hours:

rm -rf ~/.cache/gws/

Verify the service name:

# List available services
gws --help

Check Google API status: Visit Google Workspace Status Dashboard to verify the API is operational.

Pagination Issues

Error: Page token invalid

Cause: Page tokens expire after a short period (typically 15-60 minutes).

Solution: Restart pagination from the beginning. Don’t save and reuse page tokens across sessions.

Issue: --page-all returns fewer results than expected

Cause: The --page-limit default is 10 pages.

Solution: Increase the page limit:

gws drive files list --page-all --page-limit 100

Or set to unlimited:

gws drive files list --page-all --page-limit 0

Unlimited pagination can consume significant quota and time for large result sets.

File Upload Errors

Error: File not found or Permission denied

Cause: The file path is incorrect or not readable.

Solution:

# Use absolute paths
gws drive files create --json '{"name": "report.pdf"}' --upload /full/path/to/report.pdf

# Or verify relative path from current directory
ls -l ./report.pdf
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

Error: Invalid multipart request

Cause: The API method doesn’t support file uploads, or the request body is malformed.

Solution: Ensure you’re using an upload-capable method:

# Correct methods for uploads
gws drive files create --upload ./file.pdf --json '{"name": "file.pdf"}'
gws drive files update --params '{"fileId": "abc123"}' --upload ./updated.pdf

Platform-Specific Issues

Windows: PowerShell JSON escaping

PowerShell treats JSON quotes differently:

Use backticks to escape inner quotes:

gws drive files list --params '{`"pageSize`": 5}'

Or use a here-string:

$params = @'
{"pageSize": 5}
'@
gws drive files list --params $params

macOS: Keychain access denied

Error: Failed to access keychain

Cause: The CLI cannot access the macOS Keychain to store/retrieve encrypted credentials.

Solution:

1. Open Keychain Access app
2. Search for “gws”
3. Delete any existing gws entries
4. Run gws auth login again and approve keychain access when prompted

Linux: libsecret not installed

Error: Secret service not available

Cause: The Linux Secret Service backend is missing.

Solution: Install the required package:

# Ubuntu/Debian
sudo apt-get install gnome-keyring

# Fedora/RHEL
sudo dnf install gnome-keyring

# Arch
sudo pacman -S gnome-keyring

Getting Help

If you’re still experiencing issues:

Built-in Help

# General help
gws --help

# Service-specific help
gws drive --help

# Method-specific help
gws drive files list --help

# Inspect API schemas
gws schema drive.files.list

Report Issues on GitHub

File a bug report at github.com/googleworkspace/cli/issues.

Include:

• CLI version: gws --version
• Operating system and version
• Exact command you ran
• Full error output (redact sensitive information)
• Steps to reproduce

Dry Run for Debugging

Preview the request without executing:

gws drive files list --params '{"pageSize": 5}' --dry-run

This shows:

• HTTP method and URL
• Request headers
• Request body
• Authentication status

Share this output when reporting issues (remove any auth tokens).

Community Support

Check existing GitHub issues for similar problems:

• Search issues
• View discussions

Additional Resources

• Authentication Guide - Detailed auth setup
• API Not Enabled Errors - Fix accessNotConfigured errors
• Authentication Errors - OAuth and credential issues
• Google Workspace Status Dashboard - API availability