gpc-troubleshooting

gpc-troubleshooting

GPC 错误、退出代码和常见问题的统一调试指南。

适用场景

• GPC 命令失败并返回错误代码
• gpc doctor 报告问题
• CI 管道中的 GPC 步骤失败
• 行为或输出与预期不符
• 需要解读退出代码
• 需要启用详细/调试输出

所需输入

• 错误消息或退出代码 — GPC 报告的内容
• 失败的命令 — 实际运行的完整命令
• 环境 — 本地还是 CI、操作系统、Node.js 版本

处理步骤

0. 快速诊断

# 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，查看完整的退出代码参考。

1. 退出代码

代码	类别	含义
0	成功	命令成功完成
1	配置	配置错误（缺少 .gpcrc.json、字段无效）
2	用法	参数或标志无效
3	身份验证	身份验证失败（令牌过期、密钥无效、没有凭据）
4	API	Google Play API 错误（403、404、408、409、速率限制）
5	网络	连接失败、DNS 错误、超时
6	阈值	超出 Vitals 阈值，或没有返回可供比较的值（用于 CI 门控）
10	插件	插件权限验证错误

v1.0.0-rc.1 中的变更。 用法错误（未知选项、缺少参数）现在会以代码 2 退出，与本表一直以来的说明一致；此前它们以代码 1 退出。Vitals 或异常相关的 403 现在会以代码 4 退出，而不会再显示“无数据”并以代码 0 退出。退款或撤销操作在没有终端且未指定 --yes 时，会以代码 2 退出并返回 CONFIRMATION_REQUIRED。请检查所有根据特定代码执行分支的 CI 作业。

代码	退出	发生条件	修复方法
CONFIRMATION_REQUIRED	2	purchases orders refund / orders review-refund / purchases subscription revoke / external-transactions refund 在非交互模式下（CI、stdin 管道输入、--no-interactive）运行，但未指定 --yes	确认无误后添加 --yes，或使用无需该参数的 --dry-run 预览
IMAGE_SYNC_DIR_UNREADABLE	1	listings images sync 无法读取本地图片目录	修复目录权限（以及 CI 中的卷所有权）。Google Play 上的内容未发生任何更改
THRESHOLD_NO_DATA	6	vitals ... --threshold 未返回任何指标值（--app 错误、数据延迟、没有流量）	检查 --app，扩大 --days 范围，或在本次运行中移除 --threshold
THRESHOLD_INVALID	2	速率阈值为 1 或更高（v1.0.0-rc.2+）：速率是分数	--threshold 0.02 表示 2%；同时修正 vitals.thresholds.*
TRAIN_GATE_NO_DATA	6	gpc train advance 没有门控数据，因此停留在当前阶段（v1.0.0-rc.2+）	Vitals 数据会延迟 2-4 天；稍后重试
API_METRIC_GAMES_ONLY	4	对非游戏应用运行 vitals rendering（v1.0.0-rc.2+）	这是预期行为；渲染缓慢指标仅适用于游戏。这不是凭据问题
INVALID_PACKAGE_NAME	2	--app / GPC_APP 格式错误（v1.0.0-rc.2+）	使用 --app com.example.app 或 -a com.example.app

2. 身份验证错误（退出代码 3）

Read: references/error-catalog.md，查看完整的错误目录。

错误	原因	修复方法
AUTH_FAILED	凭据无效或已损坏	重新运行 gpc auth login --service-account <key.json>
AUTH_EXPIRED	令牌已过期且刷新失败	重新进行身份验证；检查网络/代理
AUTH_NO_CREDENTIALS	未配置身份验证	运行 gpc auth login 或设置 GPC_SERVICE_ACCOUNT
AUTH_INVALID_KEY	服务账号 JSON 格式错误	从 Google Cloud Console 重新下载密钥
AUTH_KEYCHAIN_ERROR	操作系统密钥链访问被拒绝	授予密钥链访问权限，或使用环境变量身份验证

# 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 错误（退出代码 4）

错误	HTTP	原因	解决方法
API_FORBIDDEN	403	权限不足	在 Play Console 中授予所需角色
API_NOT_FOUND	404	应用、轨道或资源不存在	验证软件包名称、轨道名称或资源 ID
API_CONFLICT	409	已有编辑正在进行	等待后重试；可能已有其他编辑会话处于打开状态
API_RATE_LIMITED	429	请求过多	GPC 会自动重试；增加 GPC_BASE_DELAY
API_REQUEST_TIMEOUT	408	请求超时	GPC 会采用指数退避策略自动重试
API_SERVER_ERROR	5xx	Google 服务器问题	稍后重试；查看 Google 状态信息中心
EDIT_CONFLICT	409	其他工具或用户正在进行并发编辑	一次只能进行一个编辑；检查 Fastlane 或 Play Console 是否有打开的编辑会话
API_DUPLICATE_VERSION_CODE	409	版本代码已上传	在 build.gradle 中递增 versionCode，然后重新构建
API_VERSION_CODE_TOO_LOW	400	版本代码低于当前值	每个轨道的版本代码都必须递增
API_PACKAGE_NAME_MISMATCH	400	applicationId 与目标应用不匹配	验证 applicationId 是否与目标应用匹配
API_APP_NOT_FOUND	404	开发者账号中没有该应用	验证软件包名称和开发者账号
API_INSUFFICIENT_PERMISSIONS	403	服务账号缺少权限	在 Play Console → Settings → API access 中授予所需角色
API_DECLARATION_REQUIRED	403	Play Console 中的“App content”声明尚未完成	在 Policy > App content 中完成声明。这不是权限问题；更改角色无济于事
API_ALREADY_EXISTS	409	尝试创建的资源已存在	使用匹配的 update 命令，而不是 create（例如 gpc otp offers update）
API_ENDPOINT_RETIRED	404	Google 已从其发布的 API 中移除该端点	无法通过 CLI 修复——请在 Play Console 中完成此任务。目前影响 gpc games ... set-icon
API_CHANGES_NOT_SENT_FOR_REVIEW	400/403	应用有被拒绝的更新，且需要设置审核标志	在命令中添加 --changes-not-sent-for-review 标志
API_CHANGES_ALREADY_IN_REVIEW	400	更改已在审核中，新提交会被静默取消	使用 --error-if-in-review，以防止静默取消
API_EDIT_EXPIRED	410	打开的编辑会话已过期（编辑会话在闲置约 30 分钟后过期）	GPC 现在会显示清晰的 API_EDIT_EXPIRED 消息，并建议重试命令。重试时，命令会自动创建新的编辑会话。
API_ROLLOUT_DECREASE_FORBIDDEN	400	分阶段发布的百分比只能提高，不能降低	要停止发布，请使用 gpc releases rollout halt --track production。要继续发布，请使用 gpc releases rollout increase 并指定更高的百分比。

# 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. 网络错误（退出代码 5）

错误	原因	解决方法
NETWORK_ERROR	连接失败	检查互联网连接；检查代理设置
NETWORK_TIMEOUT	请求超时	增加 GPC_TIMEOUT（默认值为 30000ms）
NETWORK_DNS	DNS 解析失败	检查 DNS 设置；尝试使用 Google DNS（8.8.8.8）
NETWORK_SSL	SSL/TLS 握手失败	为自定义 CA 设置 GPC_CA_CERT；检查代理

# 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. 配置错误（退出代码 1）

错误	原因	修复方法
CONFIG_MISSING	缺少 .gpcrc.json 或环境变量	运行 gpc setup（v0.9.68+）或 gpc config init
CONFIG_INVALID	.gpcrc.json 格式错误	验证 JSON 语法
CONFIG_INVALID_JSON	配置文件包含语法错误（v0.9.80+）	运行 cat <file> | python3 -m json.tool 查找错误
CONFIG_INVALID_KEY	键为空、格式错误或为保留名称（v0.9.80+）	使用有效的字母数字组合配置文件名/键名
CONFIG_APP_MISSING	未指定应用	使用 gpc config set app 或 --app 标志设置

配置优先级修复（v0.9.81+）： 在 v0.9.81 之前，活动配置文件会悄无声息地优先于 GPC_SERVICE_ACCOUNT/GPC_APP 环境变量以及 --service-account/--app 标志。这是一个错误。自 v0.9.81 起，已按文档规定执行优先级：标志优先于环境变量，环境变量优先于活动配置文件，活动配置文件优先于默认值。如果环境变量似乎未生效，请运行 gpc config list 检查是否设置了活动配置文件，并更新或停用它。

# Initialize config
gpc config init

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

# Check current config
gpc config list

6. 上传和发布错误

错误	原因	修复方法
INVALID_BUNDLE	AAB 已损坏或格式错误	重新构建 AAB；先运行 gpc validate
VERSION_CODE_CONFLICT	版本代码已被使用	在 build.gradle 中递增 versionCode
RELEASE_NOT_FOUND	指定的轨道上没有发布版本	检查轨道名称；使用 gpc releases list --track <track>
RELEASES_USAGE_ERROR / PUBLISH_USAGE_ERROR（退出代码 2）	发布比例不在 1-100 范围内	--rollout 和 --to 的值应为百分比：使用 --rollout 10，而不是 --rollout 0.1
PROMOTE_NO_SOURCE	源轨道没有可提升的发布版本	先上传到源轨道
UPLOAD_CHUNK_FAILED	重试后仍无法发送分块	检查网络；增大 GPC_MAX_RETRIES 或 GPC_UPLOAD_TIMEOUT
UPLOAD_NO_COMPLETION	已发送所有字节，但未收到完成响应	重试上传；检查 GPC_UPLOAD_TIMEOUT
UPLOAD_INITIATE_FAILED	会话初始化失败	检查身份验证和权限；重试
UPLOAD_NO_SESSION_URI	初始化响应中没有 Location 标头	API 错误；重试或检查服务账号权限
UPLOAD_SESSION_NOT_FOUND	会话已过期（404）	启动新的上传会话
UPLOAD_SESSION_EXPIRED	会话已失效（410）	启动新的上传会话
UPLOAD_INVALID_CHUNK_SIZE	分块大小不是 256 KB 的整数倍	将 GPC_UPLOAD_CHUNK_SIZE 设置为 262144（256 KB）的整数倍
EDIT_VALIDATE_FAILED	上传后出现暂时性的验证/提交失败	自 v0.9.77 起，会使用多次重试保护机制自动重试（15s、30s、45s）；如果问题持续存在，请检查 bundle 状态
REVIEW_SKIPPED	内部轨道提交已完成，但未进入 Google 审核队列	符合预期。internal 轨道无需审核。GPC 会在结构化 JSON 输出中设置 reviewSkipped: true（v0.9.79+），以确认提交已立即完成。

# 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

提交被拒：结构化输出中的 reviewPending（v0.9.79+）

当 Google 要求审核并因此拒绝 edits.commit 时，--json 输出会包含结构化结果，而不是普通错误：

{
  "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 流水线可以依据 reviewPending === true，决定是等待、通知还是退出。nextStep 字段始终包含关于下一步操作的易读说明。

7. Vitals 阈值超限（退出代码 6）

退出代码 6 不是错误——它表示 Vitals 指标有意超出阈值。用于 CI 门禁。

# 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. 订单退款审核错误（退出代码 2，v0.9.96+）

代码	含义	修复方法
ORDER_REVIEW_REFUND_INVALID	gpc purchases orders review-refund 输入无效：--sample-content-provided 未作答、--consumption-percent 超出 0-100，或 --usage-events-file 不是对象数组形式的 JSON	在 --sample-content-provided / --no-sample-content-provided 中恰好传入一个选项，使用 --consumption-percent 45.2 这样的普通小数，并确保文件是类似 [{ "consumptionTime": "2026-08-30T10:15:00Z" }] 的数组

请求发送前会在本地拒绝，因此命令出错不会占用 Google 24 小时响应窗口的一部分。空的或仅包含空白字符的 --consumption-percent 会视为未提供，而不是 0%。

8. 插件错误（退出代码 10）

错误	原因	修复方法
PLUGIN_INVALID_PERMISSION	第三方插件声明了未知权限	查看 plugin-sdk 文档中有效的权限
PLUGIN_PERMISSIONS_REQUIRED	第三方插件未声明 gpc.permissions（v0.9.94+）	请作者声明其使用的钩子，然后重新批准该插件
PLUGIN_IDENTITY_MISMATCH	说明符声称是第一方软件包，但解析结果指向其他位置（v0.9.94+）	移除 @gpc-cli/plugin-ci 的 npm 别名或本地替代项
插件未加载	未加入配置或未获批准	在 .gpcrc.json 的 plugins 和 approvedPlugins 中添加
钩子中的插件错误	插件处理程序存在 Bug	查看插件日志；onError/API 钩子会吞掉错误

变更日志生成错误（v0.9.61+）

代码	含义	修复方法
CHANGELOG_NO_TAG	未找到 v* git 标签，且未传入 --from	创建标签（git tag v0.0.1）或传入 --from <ref>
CHANGELOG_BAD_REF	--from 或 --to 的 ref 不存在	运行 git rev-parse --verify <ref> 进行检查
CHANGELOG_LOCALES_REQUIRED	传入了 --target play-store，但未传入 --locales（v0.9.62+）	传入 --locales en-US,fr-FR 或 --locales auto
CHANGELOG_LOCALES_INVALID	一个或多个 --locales 不符合有效的 BCP 47 格式（v0.9.62+）	使用 Play Store 支持的代码，例如 en-US、fr-FR、de-DE
CHANGELOG_LOCALES_AUTO_NO_APP	使用 --locales auto，但没有已通过身份验证的客户端和应用（v0.9.62+）	传入 --app <package> 或设置 config.app，并检查凭据
CHANGELOG_FETCH_FAILED	无法访问 GitHub API 或 API 返回了错误（v0.9.80+）	检查网络；在文档站点查看变更日志
CHANGELOG_VERSION_NOT_FOUND	在 GitHub 发行版中找不到请求的版本（v0.9.80+）	运行 gpc changelog --limit 10 查看可用版本
WATCH_WEBHOOK_FAILED	Webhook 端点返回了非 2xx 状态码（v0.9.80+）	检查 Webhook URL 和服务器状态
CHANGELOG_LOCALES_EMPTY	--locales auto 未返回任何区域设置（v0.9.62+）	至少创建一个 Play Store 商品详情，或传入明确的 --locales
RELEASE_NO_DRAFT	--apply 在目标轨道上未找到草稿发行版（v0.9.64+）	先创建草稿发行版（gpc releases upload --status draft）
BUNDLE_PROCESSING_TIMEOUT	AAB 上传已完成，但软件包在约 86 秒内仍未处理完成（v0.9.64+，v0.9.77 起已延长）	重试上传，或使用 --status draft 并稍后提交；如果问题持续，请检查软件包大小和 Google 服务器状态

批量报告错误（v0.9.93+）

gpc reports list 和 gpc reports download stats|financial 会从与开发者账号关联的 Cloud Storage 存储桶（pubsite_prod_<developerId>）读取 Play 的月度批量报告 CSV 文件。在 v0.9.93 之前，这些命令只会显示操作指引；现在它们会实际执行网络操作，并使用各自的错误代码。

代码	退出码	含义	解决方法
REPORT_ACCESS_DENIED	4	凭据有效，但无权读取报告存储桶	Play Console -> 用户和权限 -> 服务账号 -> 账号权限 -> 启用“查看应用信息并下载批量报告（只读）”，等待几分钟后重试
REPORT_AUTH_REJECTED	3	Google 拒绝了令牌本身（HTTP 401）	使用 gpc auth status 检查密钥，确认系统时钟正确，然后运行 gpc auth clear-cache 并重试
REPORT_BUCKET_UNKNOWN	2	未配置存储桶，也没有可用于推导存储桶名称的开发者 ID	设置 developerId / GPC_DEVELOPER_ID，或传入 --bucket / GPC_REPORTS_BUCKET / reports.bucket
REPORT_BUCKET_INVALID	2	配置的存储桶名称不是有效的 GCS 存储桶名称	从 Play Console -> 下载报告中复制准确的 Cloud Storage URI（接受 gs:// URI，并会提取其中的存储桶名称）
REPORT_BUCKET_NOT_FOUND	4	存储桶不存在，或此账号无法查看该存储桶	确认名称；默认值为 pubsite_prod_<developerId>
REPORT_OBJECT_NOT_FOUND	4	没有匹配类型 / 月份 / 维度的对象	错误信息会列出可用维度或月份；月份结束后才会发布报告
REPORT_LIST_FAILED	4	存储桶列表调用失败	重试；检查网络并运行 gpc doctor
REPORT_DOWNLOAD_FAILED	4	获取对象失败	重试；检查网络
REPORT_DECODE_FAILED	4	无法对对象进行 gunzip 解压或从 UTF-16 解码	重试下载；如果问题仍然存在，使用 --output-file 保存原始对象并进行报告
REPORT_ARCHIVE_UNREADABLE	4	无法读取财务 ZIP 归档	使用 --output-file report.zip 保存原始文件并在本地打开
REPORT_MULTIPLE_ENTRIES	2	财务归档中包含多个 CSV，因此无法只打印一个文件	使用 --output-file report.zip 保存归档，或使用 --json 内联输出所有条目
INVALID_REPORT_DIMENSION	2	--dimension 不是受支持的值之一	使用 overview、country、language、os_version、device、app_version、carrier 或 traffic_source（评价报告没有维度）
MISSING_REQUIRED_OPTION	2	缺少 --month 或 --type 等必需标志	查看命令概要：下载统计数据需要 --month 和 --type
INVALID_LIMIT	2	--limit 不是正整数	传入一个正整数

gpc doctor 包含 reports-bucket 探测项：当授权缺失（403/401）或存储桶名称错误（404）时，它会发出警告，因此这是在调试命令之前确认配置是否正确的最快方式。

9. 调试模式

为任何命令启用详细输出：

# 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. 可重试的 HTTP 状态码

GPC 会通过指数退避自动重试以下 HTTP 状态码：

• 408 — 请求超时
• 429 — 请求过多（受到速率限制）
• 5xx — 服务器错误（500、502、503 等）

配置重试行为：

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)

验证

• gpc doctor 通过所有检查
• 失败的命令现在可以成功执行，或显示清晰且可操作的错误
• 退出码与预期类别相符
• --json 输出包含 error.code、error.message 和 error.suggestion

故障模式 / 调试

症状	可能原因	修复方法
gpc doctor 在身份验证时失败	未配置凭据	运行 gpc setup（v0.9.68+）或 gpc auth login
gpc doctor 在 API 检查时失败	服务账号没有 API 访问权限	在 GCP 中启用 Google Play Developer API
gpc doctor 发出配额警告	每日或每分钟 API 配额使用量超过 80%	降低请求频率，或向 Google 申请提高配额（v0.9.71+）
gpc doctor 出现插件错误	已配置的插件加载失败	检查插件包版本，重新安装，或从配置中移除（v0.9.71+）
gpc doctor --verify 检测到不匹配	本地密钥库与 Play 签名证书不一致	在 Play Console 中注册本地密钥，或使用 Play App Signing（v0.9.75+）
所有命令都超时	网络 / 代理问题	检查 HTTPS_PROXY、GPC_CA_CERT、GPC_TIMEOUT
NETWORK_ERROR：“已配置代理……但无法通过代理路由请求”	HTTPS_PROXY / HTTP_PROXY 格式错误（v0.9.98+ 会直接失败，而非直连）	修正 URL（例如 http://proxy.example.com:8080）或取消设置该变量；对于应绕过代理的主机，请使用 NO_PROXY
users list / users get：“当前不支持分页”	Google 现在会拒绝分页的 users 请求（v0.9.98 之前的 GPC）	升级到 v0.9.98+
gpc doctor 警告“未知配置键：legacyApprovedPlugins、pluginApprovalPolicyVersion”（或 vitals / games / reports）	已知键列表过时（v0.9.98 之前）；这些键有效	升级到 v0.9.98+；无需更改配置
命令在本地运行正常，在 CI 中失败	CI 中缺少环境变量	在 CI 密钥中设置 GPC_SERVICE_ACCOUNT 和 GPC_APP；运行 gpc setup --auto（v0.9.68+）
环境变量 GPC_SERVICE_ACCOUNT / GPC_APP 似乎被忽略	活动配置文件覆盖了环境变量（v0.9.81 之前的 bug）	升级到 v0.9.81+。使用 gpc config list 检查活动配置文件；现在环境变量和标志会正确覆盖配置文件。
npm install -g @gpc-cli/cli 因 EUNSUPPORTEDPROTOCOL 失败	workspace:* 说明符泄漏到了已发布的清单中（v0.9.77-v0.9.83）	重新安装 v0.9.84+ 或 v0.9.85+：npm install -g @gpc-cli/cli@latest。v0.9.84 中已修复（cli+core），并在 v0.9.85 中彻底解决（api 包已重新发布）。
gpc doctor 针对 reports-bucket 发出警告	服务账号缺少批量报告授权，或存储桶名称有误	在 Play Console 中启用“查看应用信息并下载批量报告（只读）”，或使用 --bucket / GPC_REPORTS_BUCKET 设置准确的存储桶（v0.9.93+）
授予权限后，报告仍立即被拒绝	授权尚未生效，或缓存的令牌是在授权前获取的	等待几分钟，运行 gpc auth clear-cache，然后重试（v0.9.93+）
JSON 输出中没有 suggestion	意外错误类型	提交 bug 报告——所有错误都应提供建议

相关技能

• gpc-setup — 初始身份验证和配置设置
• gpc-ci-integration — CI 专项故障排查
• gpc-vitals-monitoring — 了解阈值超限
• gpc-plugin-development — 调试插件问题