Troubleshooting

Long exec calls time out at ~100s (use exec_async). VMs stuck pending usually means capacity or zero balance. Domains stuck verifying means the CNAME isn't live yet. Zero balance Suspends your VMs (recoverable 30 days; resumes on top-up). A database you can't reach is private — connect by name from the same project.

The five most common snags, and the fix for each.

A long command times out (~100s / “524”)

exec runs synchronously and is capped at roughly 100 seconds by the edge proxy — a npm ci, a build, or a big apt-get will hit it and return a timeout/524.

Fix: run long work with exec_async (start, non-blocking) + exec_poll (drain output until done). Your agent does this automatically when it expects a long command; if you’re scripting, reach for the async pair for anything over ~60s.

VM stuck in “pending” / “creating”

A VM that won’t reach running is almost always one of:

• Zero balance — a VM can’t start with no funds. Check account_status; top up if needed.
• Capacity — if a create returns a 503, there’s no host capacity right now. That’s a real limit, not a glitch — retry shortly rather than hammering.

Use wait_for_vm to block until it’s up (or times out) instead of polling by hand.

Domain stuck on “verifying”

wait_for_domain keeps returning unverified when the CNAME isn’t resolving yet:

• Confirm the CNAME you added matches the target from add_domain exactly.
• DNS propagation can take from seconds to a few minutes — give it time.
• If your DNS provider proxies records (a “proxied” / CDN toggle), make sure that matches what the add_domain response told you to set.

See Custom domains for the full flow.

”My balance hit zero — what happens?”

Your VMs are Suspended automatically: the VM is halted, every resource it held is released, billing stops, and the disk is archived for 30 days (they stay visible so you can see what happened). Top up within that window and each VM resumes automatically — same disk, same id, same public URLs. In-memory state is lost, it’s a power cycle, and coming back takes tens of seconds. After 30 days the archive is purged. See Billing FAQ.

”I can’t reach my database / connection refused”

Databases (postgres-18, mysql-8, redis-7) are not exposed publicly by design.

• From another VM in the same project: connect by the database VM’s name (e.g. db:5432) over the private project network — not over the public internet.
• From outside Superjolt: you must open_port the database port as tcp first. (Prefer keeping databases private.)
• Different projects are isolated — two VMs can only reach each other privately if they’re in the same project.