gpc-troubleshooting

Unified debugging guide for all GPC errors, exit codes, and common issues.

When to use

• GPC command fails with an error code
• gpc doctor reports issues
• CI pipeline fails with a GPC step
• Unexpected behavior or output
• Need to interpret exit codes
• Need to enable verbose/debug output

Inputs required

• Error message or exit code — what GPC reported
• Command that failed — the full command that was run
• Environment — local vs CI, OS, Node.js version

Procedure

0. Quick diagnosis

# Check GPC health
gpc doctor

# Get version info
gpc --version

# Run failing command with verbose output
GPC_DEBUG=1 gpc <failing-command>

# Get error as JSON for parsing (also: --output csv, --output tsv since v0.9.68)
gpc <failing-command> --json

Read: references/exit-codes.md for the complete exit code reference.

1. Exit codes

2. Authentication errors (exit code 3)

Read: references/error-catalog.md for the full error catalog.

# Check current auth status
gpc auth status

# Re-authenticate
gpc auth login --service-account ~/path/to/key.json

# Bypass keychain with env var
export GPC_SERVICE_ACCOUNT=$(cat ~/path/to/key.json)

3. API errors (exit code 4)

# Check if an edit is stuck
gpc apps list --json

# API errors include suggestion field
gpc releases upload app.aab --track beta --json 2>&1 | jq '.error'

4. Network errors (exit code 5)

# Increase timeout for large uploads
export GPC_TIMEOUT=120000

# Configure retry behavior
export GPC_MAX_RETRIES=5
export GPC_BASE_DELAY=2000
export GPC_MAX_DELAY=30000

# Corporate proxy
export HTTPS_PROXY=http://proxy.corp:8080

# Custom CA certificate
export GPC_CA_CERT=/path/to/ca-cert.pem

5. Configuration errors (exit code 1)

Config precedence fix (v0.9.81+): Before v0.9.81, an active profile would silently win over GPCSERVICEACCOUNT/GPC_APP env vars and the --service-account/--app flags. This was a bug. Since v0.9.81, the documented precedence is enforced: flags override env vars, env vars override the active profile, the active profile overrides defaults. If env vars appear to be ignored, check whether an active profile is set with gpc config list and either update or deactivate it.

# Initialize config
gpc config init

# Set required values
gpc config set app com.example.app

# Check current config
gpc config list

6. Upload and release errors

# Validate before uploading
gpc validate app.aab

# Check existing releases
gpc releases list --track internal
gpc releases list --track beta

# Preview upload
gpc releases upload app.aab --track beta --dry-run

Commit rejection: reviewPending structured output (v0.9.79+)

When edits.commit is rejected because Google requires review, the --json output includes a structured result instead of a plain error:

{
  "reviewPending": true,
  "nextStep": "Your changes are under Google review. Check Play Console for status or use --changes-not-sent-for-review to bypass review for non-reviewed tracks."
}

CI pipelines can key on reviewPending === true to decide whether to wait, notify, or exit. The nextStep field always contains human-readable guidance on what to do next.

7. Vitals threshold breach (exit code 6)

Exit code 6 is not an error — it's an intentional signal that a vitals metric exceeded the threshold. Used for CI gating.

# This exits 6 if crash rate > 2.0%
gpc vitals crashes --threshold 2.0

# Check the actual value
gpc vitals crashes --json | jq '.crashRate'

# In CI, use exit code to gate promotion
gpc vitals crashes --threshold 1.5 && gpc releases promote --from beta --to production

7a. Order refund review errors (exit code 2, v0.9.96+)

Rejected locally before anything is sent, so a bad command never burns part of Google's 24-hour response window. An empty or whitespace-only --consumption-percent counts as not provided rather than as 0%.

8. Plugin errors (exit code 10)

Changelog generation errors (v0.9.61+)

Bulk report errors (v0.9.93+)

gpc reports list and gpc reports download stats|financial read Play's monthly bulk-report CSVs from the Cloud Storage bucket linked to the developer account (pubsiteprod<developerId>). Before v0.9.93 these commands only printed guidance; they now do real network work, with their own error codes.

gpc doctor includes a reports-bucket probe: it warns when the grant is missing (403/401) or the bucket name is wrong (404), so it is the fastest way to confirm setup before debugging a command.

9. Debug mode

Enable verbose output for any command:

# Debug environment variable
GPC_DEBUG=1 gpc releases upload app.aab --track beta

# JSON output for machine parsing
gpc releases upload app.aab --track beta --json

# Combine for maximum detail
GPC_DEBUG=1 gpc releases upload app.aab --track beta --json 2>debug.log

10. Retryable HTTP status codes

GPC automatically retries the following HTTP status codes with exponential backoff:

• 408 — Request Timeout
• 429 — Too Many Requests (rate limited)
• 5xx — Server errors (500, 502, 503, etc.)

Configure retry behavior:

export GPC_MAX_RETRIES=5        # Default: 5
export GPC_BASE_DELAY=1000      # Initial delay in ms
export GPC_MAX_DELAY=15000      # Max delay in ms
export GPC_UPLOAD_TIMEOUT=300000  # Upload timeout in ms (5 min)

Verification

• gpc doctor passes all checks
• Failing command now succeeds or shows a clear, actionable error
• Exit code matches the expected category
• --json output includes error.code, error.message, and error.suggestion

Failure modes / debugging

Related skills

• gpc-setup — initial auth and config setup
• gpc-ci-integration — CI-specific troubleshooting
• gpc-vitals-monitoring — understanding threshold breaches
• gpc-plugin-development — debugging plugin issues