Troubleshooting

Start with what Anyport already says. A cluster's connection, an app's status, a failed build and a domain's verification each carry a sentence saying what went wrong, and every entry below starts from that sentence. When it is not enough, these are the places to look:

Connecting a cluster#

The cluster never connects, or drops off#

The agent dials out to Anyport over gRPC on port 443, and nothing ever connects in. A cluster that stays disconnected is one whose agent cannot reach Anyport, and an egress firewall or an outbound proxy is the usual cause. Allow outbound HTTPS from the anyport namespace; the agent keeps retrying, so it connects without a reinstall once the path is open.

If anyport cluster attach itself failed, the transcript in ~/.anyport/logs/ names the step. See Check that it worked.

A cluster was disconnected after 30 days#

The free plan keeps three clusters connected. With more than three, or with credit below zero, the clusters past the organization's three oldest are disconnected after 30 days, with an email at the start and another a week before. Their apps keep running. Choosing Pro, buying credit or removing clusters reconnects them, and the cluster list names any cluster due to be disconnected, and when. See Adding more clusters.

Services and storage#

A service is refused because the cluster has no storage#

Anything that keeps data, such as PostgreSQL, MySQL, durable Redis or Observability, asks the cluster for a volume. When the cluster has no storage class at all, or has classes but none marked default, Anyport refuses the install and says which, for example: "PostgreSQL needs a persistent volume, and this cluster has no storage classes. Install a CSI driver on the cluster, then try again."

• Classes, but no default. Pick a class in the service's advanced settings, or mark one default so every install gets it:

  kubectl get storageclass
  kubectl patch storageclass <name> \
    -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

  Copy

• No classes. The cluster needs a CSI driver. Clusters that need setup names the one for EKS, Cloudfleet and bare metal.

The cluster's Settings → Storage tab shows the same facts once the agent connects. After you install a driver or mark a default, just try the install again: Anyport reads the cluster's storage classes again before refusing, so the agent does not need a restart.

A service or app is stuck waiting for storage#

When a volume cannot be created, the service or app says so after about two minutes, with the reason: for example "Waiting for storage: Nothing has created this volume in 6 minutes. Storage class "gp2" uses the provisioner ebs.csi.aws.com, which is not responding." The cluster has a default storage class, so Anyport accepts the install, but the driver behind that class is not installed and the volume request is never filled. A new Amazon EKS cluster without the EBS CSI driver add-on is the common case. The cluster's Settings → Storage tab lists the same reason next to the volume.

kubectl get pvc -A

A claim whose STATUS is Pending confirms it. Install the driver and the pending claim is provisioned; the service or app starts without being reinstalled.

An app whose volume lives on one node (local-path, or a disk in one zone) reports when that node cannot run it, and an app whose new instance cannot attach its disk says so too. A disk still held by the node of the instance it replaces clears on its own; if that node is gone, Kubernetes waits about six minutes before releasing it.

Deploying apps#

The image will not pull#

The app's status says which kind of failure it is:

The app keeps restarting#

The status names the cause, in one of these forms:

• Out of memory, with the limit it went past. Raise the app's memory, or find out what grew.
• Exited with code and a number. The process stopped on its own; its last output is in anyport logs <app> -p <project>.
• Could not be created, with Kubernetes' reason. Usually a variable that references a secret, or a key in one, that does not exist.
• Cannot be scheduled. No node has room for the CPU or memory the app asks for. Ask for less, or add a node.
• Evicted by the node. The node ran short, usually of memory or disk, and removed it.

For a container that restarts too fast to open a shell in, or has no shell at all, attach a debug container instead:

anyport shell api -p demo --debug

None of this takes down a version that was already serving: a new revision that cannot start leaves the previous one in place, and the app's overview offers to roll back to it.

A build failed#

A build's reason is in its output and nowhere else. The app's own logs never see it, because the build produced no image to run.

anyport build ls --app api -p demo
anyport build logs <id> -p demo

build logs reads from the cluster's log store, so it needs Observability. A build that ran out of memory says so, and points at the build's memory setting rather than the app's. The version that was serving keeps serving.

A deploy stopped at the pre-deploy command#

When an app's pre-deploy command exits non-zero, the rollout stops there and the previous version carries on serving. Fix the command, or the migration it runs, and deploy again.

The app says it is waiting#

An app that references a managed service waits for that service before it rolls out, and a reference to another app is waited on for up to two minutes. Its status names what it is waiting for, and after fifteen minutes it asks for attention. The fix is in the dependency it names, not in the app. See Start order.

A push did not deploy#

Auto-deploy is off when an app is created, so the first deploy is always one you asked for. Turn it on in the app's Source settings. The GitHub App also needs access to the repository. Pushes that land while a build is running coalesce into one build of the newest commit, so a burst of pushes produces one deploy, not one each.

A pull request got no preview#

With When to create a preview on its default, When somebody asks, nothing is created until a person asks from the pull request or the console. If previews are set to For every pull request, check these in turn:

• Enable previews is on, under the project's Settings → Preview environments.
• The pull request is not a draft while Skip draft pull requests is on.
• The project is under its Most previews at once cap, which refuses new previews past it.
• The pull request is not from a fork. With Build pull requests from forks off, a fork's preview waits for someone who can change the project to approve it from the Previews tab.

See Preview environments.

Domains and HTTPS#

Verification fails#

"ownership TXT record not found yet. Add it, then verify (DNS can take a few minutes)." The TXT record belongs at _anyport-challenge. followed by your hostname, with the value Anyport shows: _anyport-challenge.api.acme.com for api.acme.com. Many DNS providers add the zone to whatever name you type, so entering the full name there produces _anyport-challenge.api.acme.com.acme.com; type _anyport-challenge.api instead. To see what is published:

dig +short TXT _anyport-challenge.api.acme.com

A verified domain stopped serving#

Anyport keeps checking ownership after a domain is verified. If the TXT record disappears, the domain carries a warning, and after three failed checks in a row it stops being served and returns to pending: "Ownership could not be re-confirmed". Put the record back and verify again. Leave it in place for as long as the domain is in use.

HTTPS does not work#

A custom domain gets its certificate once it is verified and its CNAME or A record points where Anyport showed. Until both are true it has none.

On a cluster you attached, certificates also need cert-manager. When Anyport installs it for you, that needs Kubernetes 1.30 or newer; on 1.29 and older the install fails, and automatic HTTPS with it. Upgrade the cluster, or install a cert-manager that supports your version first, since Anyport uses one it finds. See Cluster requirements.

Logs, metrics and tools#

Logs and metrics have no history#

Live logs and metrics work with nothing installed. Searchable history and time series come from Observability, installed once per cluster from the cluster's Services catalog. Until it is, the Logs and Metrics tabs show a banner linking to it. It keeps data, so it needs storage like any other service. See Logs & metrics.

Somewhere else#

• An AI client shows the Anyport MCP server as failed: MCP troubleshooting.
• Sign-in fails on a self-hosted console: Checking a setup.

Still stuck#

Tell us what you ran and what it said. The message from the console and, for a cluster install, the transcript in ~/.anyport/logs/ are what make it quick to answer.

Next steps#

• Cluster requirements — What a cluster needs before most of this comes up.
• CLI — Every command used on this page.
• Logs & metrics — The history behind anyport logs and anyport build logs.