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

Code	Category	Meaning
0	Success	Command completed successfully
1	Config	Configuration error (missing .gpcrc.json, invalid fields)
2	Usage	Invalid arguments or flags
3	Auth	Authentication failure (expired token, invalid key, no credentials)
4	API	Google Play API error (403, 404, 408, 409, rate limit)
5	Network	Connection failure, DNS error, timeout
6	Threshold	Vitals threshold breached, or no value came back to compare (used in CI gating)
10	Plugin	Plugin permission validation error

Changed in v1.0.0-rc.1. Usage mistakes (unknown option, missing argument) now exit 2 as this table has always said; they exited 1 before. A vitals or anomalies 403 now exits 4 instead of printing "no data" and exiting 0. A refund or revocation with no terminal and no --yes exits 2 with CONFIRMATION_REQUIRED. Check any CI job that branches on a specific code.

Code	Exit	When	Fix
CONFIRMATION_REQUIRED	2	purchases orders refund / orders review-refund / purchases subscription revoke / external-transactions refund ran non-interactively (CI, piped stdin, --no-interactive) without --yes	Add --yes once you are sure, or preview with --dry-run, which never needs it
IMAGE_SYNC_DIR_UNREADABLE	1	listings images sync could not read a local image directory	Fix its permissions (and volume ownership in CI). Nothing was changed on Google Play
THRESHOLD_NO_DATA	6	vitals ... --threshold got no metric value back (wrong --app, data lag, no traffic)	Check --app, widen --days, or drop --threshold for that run
THRESHOLD_INVALID	2	A rate threshold of 1 or more (v1.0.0-rc.2+): rates are fractions	--threshold 0.02 means 2%; fix vitals.thresholds.* too
TRAIN_GATE_NO_DATA	6	gpc train advance had no gate data and stayed on its stage (v1.0.0-rc.2+)	Vitals lag 2-4 days; run it again later
API_METRIC_GAMES_ONLY	4	vitals rendering on a non-game app (v1.0.0-rc.2+)	Expected; slow rendering is games-only. Not a credentials problem
INVALID_PACKAGE_NAME	2	Malformed --app / GPC_APP (v1.0.0-rc.2+)	--app com.example.app or -a com.example.app

2. Authentication errors (exit code 3)

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

Error	Cause	Fix
AUTH_FAILED	Invalid or corrupted credentials	Re-run gpc auth login --service-account <key.json>
AUTH_EXPIRED	Token expired and refresh failed	Re-authenticate; check network/proxy
AUTH_NO_CREDENTIALS	No auth configured	Run gpc auth login or set GPC_SERVICE_ACCOUNT
AUTH_INVALID_KEY	Malformed service account JSON	Re-download key from Google Cloud Console
AUTH_KEYCHAIN_ERROR	OS keychain access denied	Grant keychain access or use env var auth

# 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)

Error	HTTP	Cause	Fix
API_FORBIDDEN	403	Insufficient permissions	Grant required roles in Play Console
API_NOT_FOUND	404	App, track, or resource doesn't exist	Verify package name, track name, or resource ID
API_CONFLICT	409	Edit already in progress	Wait and retry; another edit may be open
API_RATE_LIMITED	429	Too many requests	GPC auto-retries; increase GPC_BASE_DELAY
API_REQUEST_TIMEOUT	408	Request timed out	GPC auto-retries with exponential backoff
API_SERVER_ERROR	5xx	Google server issue	Retry later; check Google status dashboard
EDIT_CONFLICT	409	Concurrent edit from another tool/user	Only one edit at a time; check if Fastlane or Play Console has an open edit
API_DUPLICATE_VERSION_CODE	409	Version code already uploaded	Increment versionCode in build.gradle and rebuild
API_VERSION_CODE_TOO_LOW	400	Version code lower than current	Version code must increase per track
API_PACKAGE_NAME_MISMATCH	400	applicationId doesn't match target app	Verify applicationId matches target app
API_APP_NOT_FOUND	404	App not in developer account	Verify package name and developer account
API_INSUFFICIENT_PERMISSIONS	403	Service account missing permissions	Grant required roles in Play Console → Settings → API access
API_DECLARATION_REQUIRED	403	A Play Console "App content" declaration is incomplete	Complete it under Policy > App content. Not a permissions problem; changing roles will not help
API_ALREADY_EXISTS	409	The resource you tried to create is already there	Use the matching update command instead of create (e.g. gpc otp offers update)
API_ENDPOINT_RETIRED	404	Google removed the endpoint from its published API	Not fixable from the CLI -- do the task in Play Console. Currently affects gpc games ... set-icon
API_CHANGES_NOT_SENT_FOR_REVIEW	400/403	App has rejected update, requires review flag	Add --changes-not-sent-for-review flag to the command
API_CHANGES_ALREADY_IN_REVIEW	400	Changes already in review, new commit would silently cancel	Use --error-if-in-review to prevent silent cancellation
API_EDIT_EXPIRED	410	The open edit session has expired (edits expire after ~30 minutes of inactivity)	GPC now includes a clear API_EDIT_EXPIRED message with a suggestion to retry the command. The command will automatically create a fresh edit on retry.
API_ROLLOUT_DECREASE_FORBIDDEN	400	Staged rollout percentage can only be increased, not decreased	To stop a rollout, use gpc releases rollout halt --track production. To continue, use gpc releases rollout increase with a higher percentage.

# 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)

Error	Cause	Fix
NETWORK_ERROR	Connection failed	Check internet; check proxy settings
NETWORK_TIMEOUT	Request timed out	Increase GPC_TIMEOUT (default 30000ms)
NETWORK_DNS	DNS resolution failed	Check DNS settings; try Google DNS (8.8.8.8)
NETWORK_SSL	SSL/TLS handshake failed	Set GPC_CA_CERT for custom CA; check proxy

# 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)

Error	Cause	Fix
CONFIG_MISSING	No .gpcrc.json or env vars	Run gpc setup (v0.9.68+) or gpc config init
CONFIG_INVALID	Malformed .gpcrc.json	Validate JSON syntax
CONFIG_INVALID_JSON	Config file contains syntax errors (v0.9.80+)	Run cat <file> | python3 -m json.tool to find the error
CONFIG_INVALID_KEY	Key is empty, malformed, or a reserved name (v0.9.80+)	Use a valid alphanumeric profile/key name
CONFIG_APP_MISSING	No app specified	Set with gpc config set app or --app flag

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

Error	Cause	Fix
INVALID_BUNDLE	AAB is corrupted or wrong format	Rebuild the AAB; run gpc validate first
VERSION_CODE_CONFLICT	Version code already used	Increment versionCode in build.gradle
RELEASE_NOT_FOUND	No release on the specified track	Check track name; use gpc releases list --track <track>
RELEASES_USAGE_ERROR / PUBLISH_USAGE_ERROR (exit 2)	Rollout outside 1-100	--rollout and --to are percentages: --rollout 10, not --rollout 0.1
PROMOTE_NO_SOURCE	Source track has no release to promote	Upload to source track first
UPLOAD_CHUNK_FAILED	Chunk could not be sent after retries	Check network; increase GPC_MAX_RETRIES or GPC_UPLOAD_TIMEOUT
UPLOAD_NO_COMPLETION	All bytes sent but no completion response	Retry upload; check GPC_UPLOAD_TIMEOUT
UPLOAD_INITIATE_FAILED	Session initiation failed	Check auth and permissions; retry
UPLOAD_NO_SESSION_URI	No Location header in initiation response	API error; retry or check service account permissions
UPLOAD_SESSION_NOT_FOUND	Session expired (404)	Start a new upload session
UPLOAD_SESSION_EXPIRED	Session gone (410)	Start a new upload session
UPLOAD_INVALID_CHUNK_SIZE	Chunk size not multiple of 256 KB	Set GPC_UPLOAD_CHUNK_SIZE to a multiple of 262144 (256 KB)
EDIT_VALIDATE_FAILED	Transient validate/commit failure after upload	Auto-retried with multi-retry guard (15s, 30s, 45s) since v0.9.77; if persistent, check bundle status
REVIEW_SKIPPED	Internal track commit completed without entering Google review queue	Expected behavior. The internal track does not require review. GPC sets reviewSkipped: true in structured JSON output (v0.9.79+) to confirm the commit went through immediately.

# 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 0.02

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

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

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

Code	Meaning	Fix
ORDER_REVIEW_REFUND_INVALID	gpc purchases orders review-refund was given invalid input: --sample-content-provided unanswered, --consumption-percent outside 0-100, or --usage-events-file that is not a JSON array of objects	Pass exactly one of --sample-content-provided / --no-sample-content-provided, use a plain decimal such as --consumption-percent 45.2, and make the file an array like [{ "consumptionTime": "2026-08-30T10:15:00Z" }]

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)

Error	Cause	Fix
PLUGIN_INVALID_PERMISSION	Third-party plugin declares unknown permission	Check valid permissions in plugin-sdk docs
PLUGIN_PERMISSIONS_REQUIRED	Third-party plugin declares no gpc.permissions (v0.9.94+)	Ask the author to declare the hooks it uses, then approve it again
PLUGIN_IDENTITY_MISMATCH	Specifier claims a first-party package but resolves elsewhere (v0.9.94+)	Remove the npm alias or local replacement for @gpc-cli/plugin-ci
Plugin not loading	Not in config or not approved	Add to plugins and approvedPlugins in .gpcrc.json
Plugin error in hook	Bug in plugin handler	Check plugin logs; onError/API hooks swallow errors

Changelog generation errors (v0.9.61+)

Code	Meaning	Fix
CHANGELOG_NO_TAG	No v* git tag found, --from not passed	Create a tag (git tag v0.0.1) or pass --from <ref>
CHANGELOG_BAD_REF	--from or --to ref doesn't exist	Run git rev-parse --verify <ref> to check
CHANGELOG_LOCALES_REQUIRED	--target play-store passed without --locales (v0.9.62+)	Pass --locales en-US,fr-FR or --locales auto
CHANGELOG_LOCALES_INVALID	One or more --locales are not valid BCP 47 (v0.9.62+)	Use Play Store-supported codes like en-US, fr-FR, de-DE
CHANGELOG_LOCALES_AUTO_NO_APP	--locales auto without an authenticated client + app (v0.9.62+)	Pass --app <package> or set config.app, check credentials
CHANGELOG_FETCH_FAILED	GitHub API unreachable or returned an error (v0.9.80+)	Check network; view changelog at the docs site
CHANGELOG_VERSION_NOT_FOUND	Requested version not found in GitHub releases (v0.9.80+)	Run gpc changelog --limit 10 to see available versions
WATCH_WEBHOOK_FAILED	Webhook endpoint returned non-2xx (v0.9.80+)	Check the webhook URL and server status
CHANGELOG_LOCALES_EMPTY	--locales auto returned zero locales (v0.9.62+)	Create at least one Play Store listing, or pass explicit --locales
RELEASE_NO_DRAFT	--apply found no draft release on the target track (v0.9.64+)	Create a draft release first (gpc releases upload --status draft)
BUNDLE_PROCESSING_TIMEOUT	AAB upload completed but bundle not processed within ~86s (v0.9.64+, extended v0.9.77)	Retry the upload, or use --status draft and commit later; if persistent, check bundle size and Google's server status

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 (pubsite_prod_<developerId>). Before v0.9.93 these commands only printed guidance; they now do real network work, with their own error codes.

Code	Exit	Meaning	Fix
REPORT_ACCESS_DENIED	4	Credential is valid but not authorized to read the reports bucket	Play Console -> Users and permissions -> the service account -> Account permissions -> enable "View app information and download bulk reports (read-only)", wait a few minutes, then retry
REPORT_AUTH_REJECTED	3	Google rejected the token itself (HTTP 401)	Check the key with gpc auth status, verify the system clock, then gpc auth clear-cache and retry
REPORT_BUCKET_UNKNOWN	2	No bucket configured and no developer id to derive one from	Set developerId / GPC_DEVELOPER_ID, or pass --bucket / GPC_REPORTS_BUCKET / reports.bucket
REPORT_BUCKET_INVALID	2	The configured bucket name is not a valid GCS bucket name	Copy the exact Cloud Storage URI from Play Console -> Download reports (a gs:// URI is accepted and reduced to the bucket name)
REPORT_BUCKET_NOT_FOUND	4	The bucket does not exist or is invisible to this account	Confirm the name; the default is pubsite_prod_<developerId>
REPORT_OBJECT_NOT_FOUND	4	No object matched the type / month / dimension	The error lists available dimensions or months; a month is only published after it ends
REPORT_LIST_FAILED	4	The bucket listing call failed	Retry; check network and gpc doctor
REPORT_DOWNLOAD_FAILED	4	The object fetch failed	Retry; check network
REPORT_DECODE_FAILED	4	The object could not be gunzipped or decoded from UTF-16	Retry the download; if it persists, save the raw object with --output-file and report it
REPORT_ARCHIVE_UNREADABLE	4	A financial ZIP archive could not be read	Save it raw with --output-file report.zip and open it locally
REPORT_MULTIPLE_ENTRIES	2	A financial archive holds several CSVs, so there is nothing single to print	Use --output-file report.zip to save the archive, or --json to inline every entry
INVALID_REPORT_DIMENSION	2	--dimension is not one of the supported values	Use overview, country, language, os_version, device, app_version, carrier, or traffic_source (reviews reports have no dimension)
MISSING_REQUIRED_OPTION	2	A required flag such as --month or --type was omitted	Check the synopsis: stats downloads need --month and --type
INVALID_LIMIT	2	--limit is not a positive integer	Pass a positive whole number

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

Symptom	Likely Cause	Fix
gpc doctor fails on auth	Credentials not configured	Run gpc setup (v0.9.68+) or gpc auth login
gpc doctor fails on API	Service account lacks API access	Enable Google Play Developer API in GCP
gpc doctor quota warning	>80% of daily or per-minute API quota used	Reduce request frequency or request quota increase from Google (v0.9.71+)
gpc doctor plugin error	A configured plugin fails to load	Check plugin package version, reinstall, or remove from config (v0.9.71+)
gpc doctor --verify mismatch	Local keystore differs from Play signing cert	Register local key in Play Console or use Play App Signing (v0.9.75+)
All commands timeout	Network/proxy issue	Check HTTPS_PROXY, GPC_CA_CERT, GPC_TIMEOUT
NETWORK_ERROR: "A proxy is configured ... could not route requests through it"	HTTPS_PROXY / HTTP_PROXY is malformed (v0.9.98+ fails closed instead of connecting directly)	Fix the URL (e.g. http://proxy.example.com:8080) or unset the variable; use NO_PROXY for hosts that should bypass it
users list / users get: "Pagination is not currently available"	Google now rejects paginated users requests (GPC before v0.9.98)	Upgrade to v0.9.98+
gpc doctor warns "Unknown config keys: legacyApprovedPlugins, pluginApprovalPolicyVersion" (or vitals/games/reports)	Stale known-keys list (before v0.9.98); these keys are valid	Upgrade to v0.9.98+; no config change needed
Commands work locally, fail in CI	Missing env vars in CI	Set GPC_SERVICE_ACCOUNT and GPC_APP in CI secrets; run gpc setup --auto (v0.9.68+)
Env vars GPC_SERVICE_ACCOUNT / GPC_APP seem to be ignored	Active profile overriding env vars (pre-v0.9.81 bug)	Upgrade to v0.9.81+. Check active profile with gpc config list; env vars and flags now correctly override the profile.
npm install -g @gpc-cli/cli fails with EUNSUPPORTEDPROTOCOL	workspace:* specifiers leaked into published manifests (v0.9.77-v0.9.83)	Reinstall on v0.9.84+ or v0.9.85+: npm install -g @gpc-cli/cli@latest. Fixed in v0.9.84 (cli+core) and fully resolved in v0.9.85 (api package re-published).
gpc doctor warns on reports-bucket	Service account lacks the bulk-reports grant, or the bucket name is wrong	Enable "View app information and download bulk reports (read-only)" in Play Console, or set the exact bucket with --bucket / GPC_REPORTS_BUCKET (v0.9.93+)
Reports still denied right after granting the permission	Grant has not propagated, or a cached token predates it	Wait a few minutes, run gpc auth clear-cache, then retry (v0.9.93+)
JSON output has no suggestion	Unexpected error type	File a bug — all errors should have suggestions

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