Deployment Troubleshooting

Authentication failed

Check:

gwebc --profile <profile> auth status

If necessary:

gwebc --profile <profile> auth login

A successfully readable auth-status response does not necessarily mean the session is usable. Confirm that the session is valid and not expired before mutation.

Application not found

Confirm the environment and tenant profile:

gwebc --profile <profile> app list --environment dev

The application may not be registered or owned for that tenant/environment.

Local image not found

For deploy push, verify the local Docker image exists:

docker image inspect <application>:dev

Then push through GWEB:

gwebc --profile <profile> \
  deploy push <application> \
  --environment dev \
  --local-image <application>:dev \
  --replicas <replicas> \
  --port <container-port>

External image rejected or cannot be pulled

deploy apply --image requires the referenced image to be reachable under the GWEB runtime's registry policy.

Inspect the rollout with:

gwebc --profile <profile> \
  app diagnostics <application> \
  --environment <environment>

A diagnostic such as:

state=WAITING
reason=ImagePullBackOff

means the newest pod cannot pull the requested image. Do not bypass the tenant workflow with SSH or raw Kubernetes credentials. For a locally built image, use gwebc deploy push --local-image so GWEB performs the managed registry ingestion.

Mutation not allowed

Run:

gwebc --profile <profile> environment show <environment>
gwebc --profile <profile> deploy status

Production normally reports read-only/non-mutable state for direct deployment commands.

Application is READY but latest revision has not converged

Application availability and rollout convergence are distinct.

Inspect:

gwebc --profile <profile> \
  deploy show <application> \
  --environment <environment>

gwebc --profile <profile> \
  deploy history <application> \
  --environment <environment>

gwebc --profile <profile> \
  app diagnostics <application> \
  --environment <environment>

For example, an older ReplicaSet may remain Ready and keep the service available while the newest revision is Pending. Do not treat state=READY alone as proof that the latest revision has completed.

Deployment submitted but not healthy

Use tenant-safe diagnostics first:

gwebc --profile <profile> \
  app diagnostics <application> \
  --environment <environment>

Then inspect deployment history:

gwebc --profile <profile> \
  deploy history <application> \
  --environment <environment>

Use the reported deployment result/failure classification rather than requiring raw kubectl access.

If tenant-safe diagnostics are insufficient or a platform-side error is reported, contact GWEB support with the application, environment, operation/request identifier, timestamp, and diagnostic output.

External HTTPS troubleshooting

If an application cannot reach an external service:

1. verify DNS resolution;
2. verify gwebc egress show reports ACTIVE;
3. verify the destination is public;
4. verify the destination uses TCP/443;
5. distinguish network/TLS failure from application-level HTTP responses;
6. do not open arbitrary node/application ports to solve outbound API access.

See ../gwebc/egress.md.