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 archives your VMs (recoverable 24h). 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 archive automatically: hypervisor stopped, billing stops, resources freed, rootfs preserved for 24 hours. Top up and call resume_vm within that window and the VM comes back (same disk; in-memory state is lost — it’s a power cycle). After 24h the rootfs is reclaimed. 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.