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 |
Rejected before it starts
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.
It started — then what the phases mean
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:
- Hard phases — content, files, settings. If one of these fails, the whole deploy fails with a message telling you which, and stops. Nothing is applied silently behind the error; you'll see a clear failure state, not a mystery.
- Soft phases — registrations and run commands. A problem here does not fail the deploy. It finishes in a partial state and records a warning you can read. The important files still landed.
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).
Reading a "partial" result
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.
Where to watch it
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.
After a failed deploy
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.