Deploy Doctor
When a pod is running but your app isn’t answering - visitors get a 502 - or when a deploy fails, InstaPods diagnoses it for you instead of leaving you a stack trace. You don’t turn this on; it runs by itself and writes what it found where you’ll see it. Where the verdict appears:
Each verdict has the same three parts: what’s wrong, the evidence that proves it (the actual error
line from your app’s log, the port it’s really listening on), and the fix. Where InstaPods can apply
the fix itself, the banner also shows an Apply fix button.
If nothing matches a known signature, you get an honest “we couldn’t pin this down” plus the first
error from your log - not a guess. Send us the pod name and we’ll look with you.
What it recognises on a running pod
Applying a fix
Click Apply fix in the banner. Only the pod’s owner can do this, and nothing is applied without that click - the diagnosis alone never changes your pod.- Dashboard
- API
Open the pod, read the banner, and click Apply fix. The banner then tells you what was done.
When a deploy fails
Failed deploys get their own diagnosis, on the deployment itself. It knows which step died - clone, install, build, or the app failing to stay up afterwards - so the advice matches the stage. Common verdicts include a stale or missing lockfile, a build that needs environment variables you haven’t set, a monorepo sibling package failing a build nothing serves, a dev/watch script being used to serve production, a branch that isn’t on the remote, and repo authentication. Deploy-failure verdicts are diagnosis only - there’s no Apply fix button on a deployment.”Ran out of memory on the Launch plan”
A build killed for memory says so in plain words instead of reporting exit code 137. During install and build a pod is temporarily given more memory than its plan, and released back before your app starts, so most builds fit on Launch - but a heavy production build (a large Next.js app, a Go link step) can still exceed it. Nothing is ever upgraded automatically. If you hit this, deploy again on the Build plan (2GB, $7/mo) or larger.”Your app isn’t responding” emails
InstaPods checks that your pod actually answers on its public URL. When it stops answering, we email you - you do not have to be watching the dashboard to find out your site is down. This covers pods running your own code on a preset. 1-Click App pods and AI Builder pods are not URL-probed, so they do not produce these alerts - a 1-Click App manages its own health, and a builder pod is expected to churn while you work on it.- At most one email per pod per day while it stays down, not one per check. A pod that flaps up and down will not re-send inside that window either.
- The email carries the Deploy Doctor verdict, not just “your pod is down” - the same diagnosis and suggested fix you would see on the pod’s banner, including the failing line from your app’s log when it is crash-looping.
- It stops on its own once the pod answers again. There is nothing to acknowledge or clear.
SSH Issues
”REMOTE HOST IDENTIFICATION HAS CHANGED”
This happens when a new pod reuses an SSH port previously used by a deleted pod. Fix: Remove the stale host key:instapods pods delete.
”Permission denied (publickey)”
Your SSH key isn’t authorized on the pod. Fix: Add your key:SSH connection timeout
The pod may be stopped, or the SSH port might be blocked. Fix:- Check pod status:
instapods pods get my-app - If stopped, start it:
instapods pods start my-app - Verify you’re using the correct port
Pod Issues
Pod stuck in “creating” state
Rarely, a pod creation can get stuck if the underlying container fails to start. Fix: Delete the pod and create a new one:Application not responding on the public URL
Open the pod’s detail page first - Deploy Doctor usually already names the cause, and often offers a one-click fix. The rest of this section is the manual check. Make sure your application is listening on the correct port:
For Node.js and Python, your app must bind to
0.0.0.0 (not 127.0.0.1 or localhost):
Pod shows “suspended” status
Your team’s subscription is suspended due to unpaid invoices. Fix: Go to Billing in the dashboard and pay the outstanding invoice. After payment, manually start your pods.Service Issues
Service stuck in “installing”
Service installation runs in the background and typically takes 8–15 seconds. If it’s been more than a minute:- Check the service status:
instapods services list my-app - If it shows “error”, the installation failed — check the error message
- Try removing and reinstalling:
“Plan does not allow services”
You’re on the Launch plan, which doesn’t support database services. Fix: Upgrade to the Build plan or higher from the billing page.File Issues
Files not appearing after upload
If you uploaded files via SCP or the CLI but they don’t appear in the dashboard file browser:- Verify the file path — the file browser starts from the pod’s app root (
/home/instapod/app) - Check file permissions:
instapods exec my-app -- ls -la /home/instapod/app/ - Make sure you uploaded to the correct directory (PHP uses
/home/instapod/app/publicfor web files)
“Permission denied” when writing files
Files in the app directory should be owned by theinstapod user. If they’re owned by root:
Domain Issues
Domain verification failing
- Check that the DNS record has propagated:
dig CNAME app.example.comordig TXT _instapods.app.example.com - Ensure the record matches exactly what InstaPods expects (shown on the domains page)
- Wait a few minutes and try again — DNS propagation can take time
SSL certificate not provisioning
After domain verification, SSL provisioning runs via certbot. If it fails:- Ensure the domain points to the correct server IP
- Check that ports 80 and 443 are accessible
- Try removing and re-adding the domain
Getting Help
If your issue isn’t covered here:- Check the pod’s Events tab for error details
- Check pod Logs for application-level errors
- Contact support through the dashboard