troubleshoot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Troubleshooting GuaraCloud

GuaraCloud故障排查

First Things to Check

首先检查这些内容

When something is wrong, start here:

bash

undefined

当出现问题时，先从以下步骤开始排查：

bash

undefined

1. Is the service running?

1. 服务是否在运行？

guara services info

2. What do the logs say?

2. 日志中有什么信息？

guara logs --level error --since 1h

3. What's the deployment history?

3. 部署历史是怎样的？

guara deployments list

4. Is the platform itself healthy?

4. 平台自身状态是否正常？

guara status

undefined

guara status

undefined

Health Statuses

健康状态说明

guara services info

reports these health statuses:

Status	Meaning	Action
`healthy`	All replicas running and passing health checks	No action needed
`crash_loop`	Container repeatedly crashing and restarting	Check logs: `guara logs --level error`
`image_pull_error`	Cannot pull the container image	Check deployment logs, verify build succeeded
`oom_killed`	Container exceeded memory limit	Reduce memory usage or upgrade tier — see guaracloud.com/docs
`degraded`	Some but not all replicas healthy	Check logs, may resolve on its own during rolling updates
`unknown`	Status cannot be determined	Wait a moment, then check again

guara services info

会返回以下健康状态：

状态	含义	操作
`healthy`	所有副本均在运行且通过健康检查	无需操作
`crash_loop`	容器反复崩溃并重启	查看日志： `guara logs --level error`
`image_pull_error`	无法拉取容器镜像	查看部署日志，验证构建是否成功
`oom_killed`	容器超出内存限制	降低内存占用或升级套餐——详见 guaracloud.com/docs
`degraded`	部分副本状态正常，但并非全部	查看日志，滚动更新过程中可能自行恢复
`unknown`	无法确定状态	等待片刻后再次检查

Deployment Failure Decision Tree

部署失败决策树

Deployment status is
failed
:

Check deployment logs:
```
guara logs --since 10m --level error
```
If build error → fix code/Dockerfile and redeploy:
```
guara deploy
```
If image pull error → previous build may have failed silently. Check
```
guara deployments list
```
for the last healthy deployment, then
```
guara rollback
```
If crash on startup → app fails to start. Check logs for stack traces, missing env vars, or port mismatches

Container keeps restarting (crash_loop):

Check logs:
```
guara logs --level error --since 30m
```
Common causes:
- Missing environment variables →
```
guara env list
```
  to check,
```
guara env set
```
  to fix
- Wrong port → service listens on a different port than configured. Check with
```
guara services info
```
- Missing dependencies → Dockerfile or buildpack not installing all deps
- OOM → app needs more memory than tier allows
If you can't determine the cause from logs, exec into the container:
```
guara exec -- env
```
to check runtime environment

Service stuck in
deploying
:

Wait — deployments can take up to 10 minutes
If still stuck, check
```
guara deployments list
```
for the status
The new deployment may be waiting for health checks to pass

部署状态显示
failed
：

查看部署日志：
```
guara logs --since 10m --level error
```
如果是构建错误 → 修复代码/Dockerfile后重新部署：
```
guara deploy
```
如果是镜像拉取错误 → 上一次构建可能静默失败。查看
```
guara deployments list
```
找到最后一次健康的部署，然后执行
```
guara rollback
```
回滚
如果是启动时崩溃 → 应用无法启动。查看日志中的堆栈跟踪、缺失的环境变量或端口不匹配问题

容器持续重启（crash_loop）：

查看日志：
```
guara logs --level error --since 30m
```
常见原因：
- 缺失环境变量 → 使用
```
guara env list
```
  检查，
```
guara env set
```
  修复
- 端口错误 → 服务监听的端口与配置不符。使用
```
guara services info
```
  检查
- 缺失依赖 → Dockerfile或构建包未安装所有依赖
- OOM → 应用所需内存超出套餐允许的限额
如果无法从日志中确定原因，进入容器执行命令：
```
guara exec -- env
```
检查运行时环境

服务卡在
deploying
状态：

等待——部署可能需要长达10分钟
如果仍未完成，查看
```
guara deployments list
```
的状态
新部署可能正在等待健康检查通过

Tier Limit Errors

套餐限制错误

The CLI surfaces these when a tier limit is reached:

"Resource exceeds your tier quota" → service needs more CPU/memory than tier allows
"Maximum number of projects reached" → delete an unused project or upgrade
"Maximum number of services reached" → delete an unused service or upgrade
"Build minutes quota exceeded" → wait for next billing cycle or upgrade
"Maximum number of custom domains reached" → remove an existing domain or upgrade
"Account resource pool exhausted" → scale down other services or upgrade

For all tier limits, direct the user to guaracloud.com/docs to see current tier details and upgrade options.

当达到套餐限额时，CLI会显示以下错误：

"Resource exceeds your tier quota" → 服务所需CPU/内存超出套餐允许的限额
"Maximum number of projects reached" → 删除未使用的项目或升级套餐
"Maximum number of services reached" → 删除未使用的服务或升级套餐
"Build minutes quota exceeded" → 等待下一个计费周期或升级套餐
"Maximum number of custom domains reached" → 删除现有域名或升级套餐
"Account resource pool exhausted" → 缩减其他服务规模或升级套餐

所有套餐限制相关问题，引导用户前往 guaracloud.com/docs 查看当前套餐详情及升级选项。

Authentication Errors

身份验证错误

"Authentication failed. API key is invalid or revoked" →
```
guara login
```
to re-authenticate
"Authentication failed. API key has expired" →
```
guara login
```
to generate a new key
"Not authenticated" →
```
guara login
```
"Account is suspended due to billing issues" → update payment at app.guaracloud.com
"Terms of Service must be accepted" → accept at app.guaracloud.com

"Authentication failed. API key is invalid or revoked" → 执行
```
guara login
```
重新验证
"Authentication failed. API key has expired" → 执行
```
guara login
```
生成新密钥
"Not authenticated" → 执行
```
guara login
```
"Account is suspended due to billing issues" → 在 app.guaracloud.com 更新支付信息
"Terms of Service must be accepted" → 在 app.guaracloud.com 接受服务条款

Network and Session Errors

网络与会话错误

"Could not reach GuaraCloud API" → check internet connection and API URL:
```
guara config get api-url
```
"No ready pods available" → service is not running. Start it:
```
guara services start
```
"Session disconnected due to inactivity" → reconnect by running the command again
"Maximum concurrent sessions reached" → close existing exec/proxy sessions first

"Could not reach GuaraCloud API" → 检查网络连接和API地址：
```
guara config get api-url
```
"No ready pods available" → 服务未运行。启动服务：
```
guara services start
```
"Session disconnected due to inactivity" → 重新运行命令以重新连接
"Maximum concurrent sessions reached" → 先关闭现有的exec/代理会话

Common Pitfalls

常见误区

Forgot to deploy after creating a service —
```
services create
```
does NOT trigger a build. Run
```
guara deploy
```
after.
Port mismatch — the
```
--port
```
in
```
services create
```
must match what the app listens on.
Missing GitHub App — install at github.com/apps/guaracloud if you see "No GitHub App installation found."
Env var change didn't take effect —
```
guara env set
```
triggers a rolling restart, but check logs to confirm the new process picked up the change.
DNS not propagated for custom domain —
```
guara domains list
```
shows
```
pending
```
until CNAME propagates. This can take minutes to hours.

For the full error code reference, see references/error-codes.md.

创建服务后忘记部署 ——
```
services create
```
不会触发构建。创建后需执行
```
guara deploy
```
。
端口不匹配 ——
```
services create
```
中的
```
--port
```
参数必须与应用监听的端口一致。
未安装GitHub App —— 如果看到"No GitHub App installation found."，请前往 github.com/apps/guaracloud 安装。
环境变量变更未生效 ——
```
guara env set
```
会触发滚动重启，但需查看日志确认新进程已加载变更。
自定义域名DNS未完成解析 ——
```
guara domains list
```
显示
```
pending
```
状态直到CNAME解析完成，此过程可能需要数分钟到数小时。

完整的错误代码参考，请查看 references/error-codes.md。