Gpc Troubleshooting

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 GPC_SERVICE_ACCOUNT/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

8. Plugin errors (exit code 10)

Changelog generation errors (v0.9.61+)

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

Error Catalog

All known GPC error codes with causes and fixes.

Authentication errors (exit code 3)

API errors (exit code 4)

Network errors (exit code 5)

Configuration errors (exit code 1)

Upload errors (exit code 4)

Release errors (exit code 4)

Monetization errors (exit code 4)

User and tester errors (exit code 4)

Plugin errors (exit code 10)

Review-state errors (exit code 4)

API_CHANGES_NOT_SENT_FOR_REVIEW

HTTP: 400 or 403

Cause: The app has been flagged by Google Play and any update must explicitly acknowledge that changes are not sent for review. This commonly happens when a previous submission was rejected or when the app is in a policy compliance state that requires the flag.

Fix: Add the --changes-not-sent-for-review flag to your release or upload command.

# Upload with the required flag
gpc releases upload app.aab --track production --changes-not-sent-for-review

# Promote with the required flag
gpc releases promote --from beta --to production --changes-not-sent-for-review

JSON error output:

{
  "success": false,
  "error": {
    "code": "API_CHANGES_NOT_SENT_FOR_REVIEW",
    "message": "This app requires the changesNotSentForReview flag to be set",
    "suggestion": "Re-run the command with --changes-not-sent-for-review"
  }
}

Notes:

• This flag tells the API that you acknowledge the changes will not be sent for review automatically.
• Some apps enter this state after a policy violation or rejected review.
• The flag is safe to include on every call if your workflow requires it.
• Technical detail (v0.9.52+): When this flag is set, GPC skips the edits.validate API call and goes straight to edits.commit. Google's validate endpoint does not accept the changesNotSentForReview parameter and returns "Unknown name" if you try. The commit endpoint handles validation internally.
• Requires GPC v0.9.52+. Versions 0.9.51 and earlier had a bug where edits.validate blocked this flag from ever reaching edits.commit.

---

API_CHANGES_ALREADY_IN_REVIEW

HTTP: 400

Cause: The track already has changes that are currently being reviewed by Google Play. Committing a new edit would silently cancel the in-progress review and replace it with the new submission, which may not be what you intended.

Fix: Use --error-if-in-review to make GPC fail early instead of silently replacing the in-review changes. If you do want to replace the in-review changes, omit the flag.

# Fail early if changes are already in review (recommended for CI)
gpc releases upload app.aab --track production --error-if-in-review

# If you intentionally want to replace the in-review release, omit the flag
gpc releases upload app.aab --track production

JSON error output:

{
  "success": false,
  "error": {
    "code": "API_CHANGES_ALREADY_IN_REVIEW",
    "message": "Track already has changes in review; committing would cancel the pending review",
    "suggestion": "Use --error-if-in-review to prevent silent cancellation, or omit the flag to replace the in-review changes"
  }
}

Notes:

• In CI pipelines, always use --error-if-in-review to avoid accidentally overwriting a release that is under review.
• If you need to check the current review state before uploading, use gpc releases list --track <track> --json to inspect the release status.
• Without this flag, GPC will proceed and the previous in-review submission will be silently cancelled by the Google Play API.

---

Signing errors (exit code 4 or 6)

EDIT_CREATE_FAILED

Cause: Failed to create an edit session via the Play API. Usually a permissions issue with the service account.

Fix: Ensure the service account has "Release manager" or "Admin" role in Play Console (Setup > API access). Check that the package name is correct.

BUNDLES_LIST_FAILED

Cause: Failed to list bundles for the app within the edit session.

Fix: Verify the app has at least one uploaded AAB. Check service account permissions.

NO_BUNDLES

Cause: The bundles list returned empty. No AABs have been uploaded to this app.

Fix: Upload at least one AAB: gpc publish or gpc releases upload app.aab --track internal.

NO_SIGNING_CERT

Cause: The generatedApks endpoint returned no signing certificate fingerprint for the bundle version. This can happen if the service account lacks sufficient permissions or if Play App Signing is not enrolled.

Fix: Enroll in Play App Signing in Play Console. Ensure the service account has access to view generated APKs.

GENERATED_APKS_FAILED

Cause: HTTP error fetching generated APKs for a specific version code.

Fix: Check that the version code exists and the service account has permissions.

Signing key mismatch (exit code 6)

Cause: gpc preflight signing detected that the signing certificate changed between your two most recent bundle versions. This could indicate an unintended key rotation or a misconfigured upload.

Fix: If the change was intentional (key upgrade), this is safe to ignore. If not, investigate which build produced the mismatched bundle.

---

Environment variables for error recovery

Exit Code Reference

Complete reference for all GPC exit codes and their meaning.

Exit codes

Using exit codes in scripts

# Simple check
gpc vitals crashes --threshold 2.0
if [ $? -eq 6 ]; then
  echo "Crash rate too high — blocking promotion"
  exit 1
fi

# Case statement
gpc releases upload app.aab --track beta
case $? in
  0) echo "Upload successful" ;;
  3) echo "Auth failed — re-authenticate" ;;
  4) echo "API error — check permissions" ;;
  5) echo "Network error — check connectivity" ;;
  *) echo "Unknown error" ;;
esac

Using exit codes in CI

GitHub Actions

- name: Check vitals
  id: vitals
  continue-on-error: true
  run: gpc vitals crashes --threshold 1.5

- name: Block if threshold breached
  if: steps.vitals.outcome == 'failure'
  run: |
    echo "Vitals check failed — blocking deployment"
    exit 1

GitLab CI

check-vitals:
  script:
    - gpc vitals crashes --threshold 1.5
    - gpc vitals anr --threshold 0.4
  allow_failure: false  # Block pipeline on exit code != 0

JSON error output

All errors include structured JSON when using --json:

{
  "success": false,
  "error": {
    "code": "API_FORBIDDEN",
    "message": "Service account lacks permission to manage production releases",
    "suggestion": "Grant 'Release to production' permission in Play Console → Users & permissions"
  }
}

Fields:

• code — machine-readable error identifier
• message — human-readable description
• suggestion — actionable fix (present on all GPC errors)

Exit code 6 — threshold breach

This is not an error — it's an intentional signal for CI gating.

# Returns exit 0 if crash rate ≤ 1.5%, exit 6 if > 1.5%
gpc vitals crashes --threshold 1.5

# JSON output includes threshold details
gpc vitals crashes --threshold 1.5 --json

{
  "success": false,
  "thresholdBreached": true,
  "value": 2.3,
  "threshold": 1.5
}