Troubleshooting a deploy
Each section is one state the dashboard can show you, why it happens, and the one thing that moves it forward.
Setup pending
What you see: the project or repo card reads Setup pending and the project page shows Finish setup.
Why: importing a repo opens a pull request that adds the deploy workflow. Nothing deploys until that PR is merged.
Do this: open the project page and click Merge & deploy, or merge the PR on GitHub. A monorepo import opens one PR for all selected workspaces.
App VM not online
What you see: a server app deploy rests at Pinned with "Your App VM has not come online yet".
Why: the bundle is published, but the App VM that should run it has not reported in. Either you have no App VM yet, it is still being prepared, or preparing it failed.
Do this: open App VM in the sidebar.
- No VM yet: create one. Your server apps deploy on it once it comes up.
- Preparing: the page shows each stage. It usually takes about 6 minutes; if it runs past 20 minutes, the page offers to delete the VM and start over.
- "We could not prepare your VM.": click Try again if it is offered (your SSH keys are filled in), otherwise Delete and create a new one.
The pinned deploy installs itself once the VM reports.
App VM running but not reachable
What you see: a server app deploy rests at Pinned with "Your App VM is running, but Stasho cannot reach it". This shows once Stasho has failed to reach the VM for five minutes in a row. The App VM page's status card reads "Running, but Stasho cannot reach it."
Why: the VM is running, but the network of the host it runs on is not routing traffic to it. Stasho cannot see the VM, so the deploy can't be confirmed live, and visitors likely can't reach it either. Re-checking will not change that.
Do this:
- Check status.stasho.xyz first. If Stasho itself is having an incident, wait for it to clear.
- Otherwise, wait. Stasho restarts the VM, and if it stays unreachable it moves the VM to a new host on its own: the status card says it is moving your VM to a new host (about 10 minutes), and your apps redeploy there. You get an email when the move is done, or one saying the VM is down if it failed, in which case the status card offers Create a new VM. See When your VM moves.
Not a site
What you see: a workspace in the import list is greyed out with "Not a site: no build script and no index.html".
Why: the folder has nothing Stasho can serve. Library packages (packages/shared, packages/utils) and workers usually look like this.
Do this: import only the workspaces that are sites or server apps. If the folder really is a site, add a build script to its package.json or an index.html at its root and re-scan.
Next.js server app on the static target
What you see: saving Settings is refused with "A Next.js server app can't deploy as a static site".
Why: a Next.js app without output: "export" builds server code, not static files. Publishing its .next/ folder serves nothing and is usually over the size limit.
Do this: either keep Server app (App VM) as the deploy target, or add output: "export" to next.config, push, then Re-detect in Settings so the framework becomes Next.js (static export) and the output directory becomes out. Pages that use SSR or API routes will not work as a static export.
Deploy target changed
What you see: a deploy reads Failed with "Deploy target changed".
Why: you switched the project between static site and server app. The earlier deploy was built for the other target and can no longer be served.
Do this: click Redeploy. The next build uses the new target.
Build too large
What you see: a deploy fails with "Build is N MB, the limit is 200 MB" or "Build has N files, the limit is 10000".
Why: static deploys are capped at 200 MB unpacked, 50 MB compressed, and 10000 files. A build that large usually includes something that is not the site: a framework cache, source maps, or node_modules.
Do this: check the Output directory in Settings points at the built site (dist, out, build), not the project root or a framework work folder like .next. Then Redeploy.