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. Usually the VM is still booting; sometimes the host it landed on never started it.
Do this: open App VM in the sidebar. The Boot step shows how long the VM has been starting and, after five minutes, offers Delete and start over, which places a new VM on a different host. 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 reads Unreachable since last check.
Why: the VM booted and you endorsed it, 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 open App VM in the sidebar, click Delete App VM, then provision a new one. New VMs are only placed on hosts running aleph-vm 2.x. Deleting stops every app on this VM and discards its local disk; apps redeploy on the new VM.
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.