Common Issues

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

Wait and retry: Most quotas reset daily or per minute

Use pagination delay: Add --page-delay to slow down requests:

gws drive files list --page-all --page-delay 1000  # 1 second between pages

Reduce page size: Request fewer items per page:
```
gws drive files list --params '{"pageSize": 10}'
```

Long-term solutions

Request a quota increase:

Go to Google Cloud Console > IAM & Admin > Quotas
Filter by the API service (e.g., “Gmail API”)
Select the quota metric you need to increase
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:

Update your system’s CA certificates:

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

# macOS
brew install ca-certificates

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 keychainCause: The CLI cannot access the macOS Keychain to store/retrieve encrypted credentials.Solution:

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

Linux: libsecret not installed

Error: Secret service not availableCause: 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:

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

Get Started

Core Concepts

Authentication

Command Reference

Advanced Usage

AI Integration

Development

Troubleshooting

Command Not Found

Error: `gws: command not found`

JSON Parsing Errors

Error: `Failed to parse JSON`

Error: `Missing required field`

Rate Limiting

Error: `429 Too Many Requests`

Network Errors

Error: `Connection timeout` or `DNS resolution failed`

Error: `SSL certificate problem`

Discovery Document Errors

Error: `Failed to fetch discovery document`

Error: `Page token invalid`

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

File Upload Errors

Error: `File not found` or `Permission denied`

Error: `Invalid multipart request`

Platform-Specific Issues

Getting Help

Built-in Help

Report Issues on GitHub

Dry Run for Debugging

Community Support

Additional Resources

Get Started

Core Concepts

Authentication

Command Reference

Advanced Usage

AI Integration

Development

Troubleshooting

​Command Not Found

​Error: gws: command not found

​JSON Parsing Errors

​Error: Failed to parse JSON

​Error: Missing required field

​Rate Limiting

​Error: 429 Too Many Requests

​Network Errors

​Error: Connection timeout or DNS resolution failed

​Error: SSL certificate problem

​Discovery Document Errors

​Error: Failed to fetch discovery document

​Pagination Issues

​Error: Page token invalid

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

​File Upload Errors

​Error: File not found or Permission denied

​Error: Invalid multipart request

​Platform-Specific Issues

​Getting Help

​Built-in Help

​Report Issues on GitHub

​Dry Run for Debugging

​Community Support

​Additional Resources

Command Not Found

Error: `gws: command not found`

JSON Parsing Errors

Error: `Failed to parse JSON`

Error: `Missing required field`

Rate Limiting

Error: `429 Too Many Requests`

Network Errors

Error: `Connection timeout` or `DNS resolution failed`

Error: `SSL certificate problem`

Discovery Document Errors

Error: `Failed to fetch discovery document`

Pagination Issues

Error: `Page token invalid`

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

File Upload Errors

Error: `File not found` or `Permission denied`

Error: `Invalid multipart request`

Platform-Specific Issues

Getting Help

Built-in Help

Report Issues on GitHub

Dry Run for Debugging

Community Support

Additional Resources