Logs + status

Where to look when something's off.

Deployment statuses

In the dashboard, a deployment is always in one of these states:

Status	Meaning
pending	Accepted, queue waiting. Should move to building within seconds.
building	Building the container image. Usually 30–90 s.
pushing	Saving the image and pushing it to your registry (if one is connected).
running	Container is up; URL is live; serving traffic.
failed	Something broke. See the status message + logs.
stopped	Container is intentionally not running. Redeploy or delete.

The deployment detail page in the dashboard shows the current status plus a progress rail when it's mid-deploy.

Reading logs

app.agentry.run/deployments → click your deployment → Logs tab.

What you'll see:

• stdout / stderr from your container, streamed in real time.
• Boot messages first, then per-request logs.
• Errors thrown but not handled show up as stack traces.

If logs aren't appearing, the container either crashed at startup or never accepted a request. Check the status message at the top of the detail page — that's where build and runtime errors land.

Common log shapes

Database connection refused

Error: connect ECONNREFUSED 10.0.0.1:27017

The DB URL is reaching the container but the host is unreachable from your server. Causes:

• The DB is on a private network your server can't reach.
• A firewall rule blocks the connection.
• You bound a dev URL into production env without realizing.

Fix: override MONGODB_URL (or your equivalent) in the deployment Env tab with the correct address. Redeploy.

Missing env var

Error: ANTHROPIC_API_KEY is not defined

The variable wasn't in the deployment's env. Either:

• You haven't bound the service yet — bind it on the server, then redeploy. The deployment doesn't inherit from server bindings automatically after it was created; you need to redeploy.
• Or you have it as NEXT_PUBLIC_* and a server-side route is reading the un-prefixed name. Pick one.

Port mismatch

Server listening on port 5173

…but the deployment URL returns connection refused.

agentry expects deployments to listen on the port specified at deploy time (default: 3000 for Node, 8000 for Python, etc.). If your app listens on a different port, set the Port field in the deployment form to match.

Build worked, container won't start

Failed to compile.

…on first request (not at deploy time).

Probably a runtime config error — something the build didn't catch but Next.js / Vite trips on at the first request. Common culprits:

• A required env var that's used inside an API route, not the build.
• A file path that's correct in dev but wrong in the built image (case-sensitivity bites on Linux).

Read the logs around the error to find which file the runtime is complaining about, fix it in the source sandbox, redeploy.

Tunnel health

Every deployment URL routes through the agentry bridge. The deployment detail page shows a Tunnel routes synced to bridge indicator. Possible values:

Indicator	What it means
Green: "Tunnel routes synced to bridge"	Healthy. The bridge knows about this URL.
Amber: "Tunnel sync stale (N s)"	The control plane hasn't been able to refresh the route table in N seconds. Hover for details.
Grey: "Tunnel sync pending…"	The control plane just started up; first sync hasn't completed. Should clear within ~10 seconds.

A persistent amber state means the bridge is unreachable from the control plane — usually a network issue on our side, not yours. Your URL keeps serving on the last-pushed route until sync resumes.

Restart, don't delete

If a deployment seems wedged but the build is fine, stop and redeploy (preserves the deployment row, URL stays the same):

1. Deployment detail page → Stop deployment.
2. Wait for status to flip to stopped.
3. Click Redeploy.

Don't Delete unless you really want the URL gone permanently — deleted deployments can't be revived.

What logs we can see

agentry's edge sees:

• HTTP requests landing at your deploy URL (method, path, status, byte count, timing).
• Container start / stop events.
• Health checks.

agentry's edge does NOT see:

• Request or response bodies.
• Your container's stdout/stderr (those are on your server; the dashboard streams them via the tunnel for you, but agentry doesn't store them).

Exporting logs

For production apps, point your container at an external log aggregator (Datadog, BetterStack, Loki, etc.) by setting the appropriate env in the deployment. agentry doesn't run a log aggregator for you.

Next

• Ship an app — the deploy flow.
• Environment variables — the most common cause of "works in dev, broken in prod".
• Troubleshooting — every common deploy error and its fix.