Troubleshooting

Start with the narrowest failed boundary and preserve evidence before restarting everything. Most incidents become much easier when you can answer: which revision, which workload, which request, which dependency, and when?

If Tabbify manages the environment, use this guide to collect the first facts and contact the named engineer through the agreed support route. You are not expected to debug the platform alone.

Diagnostic order

Work from source to destination:

1. Deploy — did the intended commit build and reach a terminal state?
2. Runtime — is the new workload running and passing readiness?
3. Application — does the process handle a local or private request?
4. Route — is traffic aimed at the intended application and path?
5. Network and policy — can this workload identity reach this dependency?
6. Data or external provider — is the dependency healthy, authorized, and within quota?

Do not start with DNS if the deploy failed to build. Do not rotate database credentials if the application never started. The first broken boundary is usually the most useful one.

Collect these facts first

Record:

• tenant, environment, application name, and application UUID;
• deploy ID, source repository, branch, and commit SHA;
• first observed time with timezone and whether the problem is ongoing;
• one failing route and, if present, its request ID;
• expected result and actual status or error;
• last known healthy revision and recent configuration changes;
• whether every user, one tenant, one route, or one operation is affected.

Remove tokens, passwords, personal data, and private payloads before sharing logs.

A deploy does not start

First inspect the deploy state and bounded log tail. The remote deploy API is asynchronous: submission returns a deploy ID, then status reports the current build or activation stage. A successful submission is not a healthy deployment.

Common causes:

Read Deploy pipeline and tabbify.toml for the exact path and configuration.

The app is running but unreachable

Separate public routing from the private application path.

1. Confirm the application UUID in the URL matches the deployed record.
2. Confirm the runner reports running and the application health is serving.
3. Verify the process listens on the configured port and on an address reachable from the microVM boundary—not only 127.0.0.1 inside the guest.
4. Try the simplest known route such as a health endpoint.
5. Check whether the failure is 400, 404, 502, a timeout, or an application response.

Interpret the boundary:

• 400 at the app route often means a malformed application UUID;
• 404 may be a valid response from your application or a wrong path;
• 502 from the edge means the node could not complete the hop to the workload;
• a timeout can be a network path, an overloaded process, or a downstream dependency;
• a normal application error proves the route reached your code.

See Routing & public access for the public request path.

The app starts and then restarts

Look at the first process exit rather than only the later crash-loop message. Check:

• entrypoint and executable permissions;
• required environment variables and mounted configuration;
• configured memory and CPU against startup demand;
• listening port and readiness deadline;
• inability to connect to a mandatory database or provider;
• an immediate migration failure;
• architecture or kernel requirements that do not match the runtime.

The supervisor uses backoff and a crash-loop threshold. Repeated manual restarts can hide the original error and delay useful logs. Read The Runtime for restart behavior.

A same-tenant private call returns 401 or 403

An address is not authorization. Confirm all of the following:

1. both applications belong to the intended tenant network;
2. the provider's private workload address and port are correct;
3. ACL policy makes the required peers visible;
4. the production relay path is connected;
5. the provider's own credential and application policy accept the request.

Diagnose each HTTP hop separately. Tabbify currently supports this pattern only inside one tenant; it does not provide a shared service catalogue or delegated access between tenants. Read Services.

Peers do not connect

Check the private mesh in this order:

• join token is valid and its claims contain the required tags;
• the coordinator can see a current heartbeat;
• ACL policy makes the peers visible to each other;
• the managed relay connection is established;
• the supervisor advertises the expected application ULA.

Production workload traffic is relay-only today. Do not spend incident time trying to establish a peer-to-peer path as a prerequisite for service. See Private Mesh for the current transport and security boundary.

Database connection failures

Classify the error before changing credentials:

• name or address failure — wrong endpoint or missing private route;
• timeout — reachability, policy, saturation, or a stalled service;
• authentication failure — wrong user, secret, rotation state, or database;
• too many connections — pool size multiplied across workloads exceeds capacity;
• permission denied — the application role lacks a required schema or operation;
• migration lock or timeout — a schema change conflicts with live traffic.

Check whether the same credentials work from an approved workload and verify the pool size on the selected application target before increasing the database connection limit. Early-access data resources have resource-specific durability and recovery limits; see Managed data.

Object storage or KV failures

For object storage, verify bucket, key or prefix, region, signing clock, content length, and permission. A signed URL can be valid but expired; an access key can be valid but scoped to a different bucket.

For KV, verify namespace, key prefix, TTL, value size, memory pressure, and whether eviction is allowed. A missing cache key and lost durable state are different incidents; the service's intended durability decides which one it is.

MCP client cannot act

Distinguish connection from authorization:

• the client can reach the MCP endpoint;
• its token is valid for the tenant and has the required scopes;
• the requested tool is available from that endpoint;
• any sensitive action is allowed by the credential and current policy;
• the client sends the protocol version and request shape expected by the server.

Do not paste a long-lived production token into a shared client configuration. Use a scoped credential and revoke it when the integration is removed. See Connect an MCP client.

Recover from a failed release

Tabbify does not currently provide an automated platform rollback operation. Identify the last known-good source commit, submit it as a new remote deployment, and follow its health and activation status. Preserve the failed deploy ID and bounded log tail before replacing it.

Redeploying application code cannot reverse an incompatible data migration. If the schema changed, use the release-specific forward-fix or exercised restore procedure.

Escalate with a useful incident packet

If your agreement includes managed incident response, contact the named engineer through the contracted route for security events, suspected data loss, failed restoration, persistent production outage, or loss of control-plane access. Include the facts from the first section plus:

• relevant deploy and application status;
• a small log excerpt around the first error;
• exact status codes and the failing hop;
• changes attempted after the failure;
• whether a known-good deployment or traffic isolation is safe.

The contracted engineer coordinates the agreed platform evidence and recovery steps. Never send credentials or full customer datasets in a support message.