GuidesOnly show guides for your app
GuidesGuidesDeploying a starter template runs a short pipeline on your server. It can be turned away at the door, or finish partway with warnings — this decodes both, so you know exactly what happened and what to do.
A one-click template writes starter files onto your server through a small pipeline. When it doesn't go smoothly, it fails in one of two clearly-different ways: it's rejected before it starts, or it runs and finishes with warnings. Each has a readable message. This guide walks both.
| At a glance | |
|---|---|
| You need | A template you're deploying from a guide page or the Templates page |
| Key idea | Rejected = nothing changed. Warned = it ran, with notes to read |
If the deploy never begins, the page shows why. These are the reasons:
| Message | Why | What to do |
|---|---|---|
| "This starter template needs … a premium plan" | The template is marked premium-only and you're on the free plan | Most starters are free; a few need premium. Use one that fits your plan, or upgrade |
| "This template requires the X application, but the server runs something else. Confirm the switch…" | The template targets a different application than your server currently runs | Confirm the switch and retry — but note it reinstalls the server and wipes files first |
| "A deployment is already running for this server. Wait for it to finish first." | Only one deploy runs per server at a time | Wait for the current one to finish, then retry |
| "Too many requests" / rate limited | You've deployed many times in a short window (about 10 per hour) | Wait a bit and try again |
| "This template's manifest failed validation…" | Rare — the template itself is broken or exceeds your plan's caps | Report it to support; it's not something you can fix |
| A permission error | A sub-user needs file permissions to deploy (and file-delete to switch applications) | Grant the permission on the Subusers page |
⚠️ Heads up: Switching applications is the one action that wipes the server — it reinstalls with the new runtime. A template that matches your current application never does this; it only overwrites files that share a name. See One-click templates.
Once accepted, the deploy runs phases in order, with a live progress bar:
content → files → settings → registrations → run → finalize
The phases split into two kinds, and the difference decides what a failure means:
So the state you end in tells you the story: completed (all clean), partial (finished, with warnings worth reading), or failed (a hard phase stopped it).
Partial means "it worked, but here's what I skipped." The warnings you might see:
| Warning | Meaning |
|---|---|
| "Modrinth items are not yet supported… use direct URLs" | A content item was skipped; the rest still installed |
| "Archive assets are not installed alongside direct files… skipped" | The template mixed file downloads and archives; the archives were skipped |
| "Unknown environment variable '…' was ignored" | A variable in the template didn't match one your application has |
| "Could not create schedule '…'" / access grant / webhook | A registration step didn't complete — set it up by hand afterward |
| "The server did not come online in time to run commands" | The post-setup commands were skipped because the server wasn't ready |
| "Some content files need attention after installation" | The content installer finished but flagged files to check |
None of these lose your starter files — they're the extras (schedules, access grants, post-run commands) that couldn't finish. Read the warning, then do that one step manually.
The guide page polls the deploy and shows the current phase and percentage; the server's Templates page shows the same phase-by-phase progress. If a deploy seems stuck, that progress view is where you confirm which phase it's in — a long content phase (downloading plugins/mods) is normal, not a hang.
🎯 Good to know: A deploy has a time budget. If a download or the "wait for the server to come online" step runs long, the job ends with a timed-out message rather than hanging forever — safe to read the result and retry.
A failed hard phase leaves the deploy stopped with a reason. Fix the named cause and deploy again — a fresh deploy just overwrites the same-named files, so retrying is safe. If the server itself won't start afterward, that's a separate step: When your server won't start. If a dependency install is what broke, see When dependencies won't install.