Troubleshooting Playbook
Start with the visible state. Do not guess from the infrastructure layer. The product should show enough context to decide whether the next owner is the user, tenant admin, app owner, or platform support.
First Triage
- Confirm tenant and project.
- Confirm the action attempted.
- Check whether the problem is account, access, quota, capacity, runtime, route, storage, billing, or cleanup.
- Capture the visible state and correlation ID.
- Retry only when the UI or API says retry is safe.
- Escalate to the correct owner with the evidence packet below.
Evidence Packet
Tenant:
Project:
User or service account:
Runtime, app, allocation, or resource:
Action attempted:
Visible state:
Correlation ID:
Timestamp and timezone:
Expected result:
Actual result:
Recent change:
Never include bearer tokens, cookies, private keys, one-time MFA codes, QR seeds, passwords, provider payloads, or raw secrets.
Blocked-State Matrix
| State | What it usually means | First owner | What to do |
|---|---|---|---|
| Tenant missing | User is not mapped to the expected workspace. | Tenant admin | Confirm invitation, identity mapping, and tenant membership. |
| Project missing | User lacks project membership or project is not active. | Tenant admin or project owner | Grant project role or switch to the right project. |
| Access denied | Current role cannot perform the action. | Tenant admin | Confirm role and least-privilege expectation. |
| MFA required | Account needs factor setup or recovery. | User, then tenant admin | Complete setup or start recovery. |
| SSH key missing | Runtime requires SSH access and no public key is available. | User | Add a public key under Account Security. |
| Catalog empty | Entitlement, quota, region, or catalog visibility is not ready. | Tenant admin | Confirm project entitlement and target region. |
| Capacity unavailable | Requested SKU or region has no matching capacity. | Tenant admin or support | Pick another profile or request capacity help. |
| Billing restricted | Balance, entitlement, or billing policy blocks launch. | Tenant admin or billing owner | Review balance, quota, and billing status. |
| Quota blocked | Project or tenant quota is exhausted. | Tenant admin | Release unused work or request quota change. |
| Provisioning failed | Runtime setup did not finish. | Platform support | Send workload ID and correlation ID. |
| Connect failed | Runtime exists but route, SSH, terminal, or endpoint is not working. | User, app owner, or support | Confirm active state, retry once, send route/action evidence. |
| Storage denied | Project, user, or service account lacks storage access. | Project owner | Confirm bucket ownership, role, and mount policy. |
| Release failed | Cleanup needs retry or operator assistance. | User, then support | Use visible retry; escalate if retry remains blocked. |
API And SDK Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
token_missing | No bearer token was sent. | Send Authorization: Bearer <token>. |
token_invalid or token_expired | Token is wrong or expired. | Refresh login or token. |
insufficient_permissions | Role is too narrow for the action. | Ask admin to review project role. |
validation_error | Request shape is invalid. | Fix the request body and required fields. |
allocation_not_found | Resource does not exist in this project or user context. | Check project ID and allocation ID. |
sku_unavailable | Requested capacity profile is unavailable. | Choose another SKU or region. |
rate_limit_exceeded | Automation is calling too often. | Back off and retry with jitter. |
Log the correlation_id with your application error. Do not log token values.
App Developer Triage
When an app launch or route fails, check:
- manifest endpoint name and port;
- endpoint auth pattern;
- artifact digest and promotion state;
- required inputs and defaults;
- health check path;
- storage mount and permissions;
- release cleanup behavior.
If the app works only with manual operator steps, it is not ready for user promotion.
When The Docs Are Not Enough
If the product page does not explain a blocked state, send the evidence packet and say which page was unclear. That is a documentation and product gap, not a user failure.