Error codes
Every message the CLI prints starts with what it was trying to do, like Couldn't create slice: … or Couldn't deploy atomic function: …, and ends with the reason. This page is the reasons: what produces each one, and what to do about it.
The CLI does not invent an error surface. It renders the status the platform returned plus whatever the platform said about it, so if you see a sentence that is not here, it came from the platform verbatim and means what it says.
A message built from an HTTP status also carries a stable code on its own line beneath it, like DRIFT-1006 · drift doctor explain DRIFT-1006. drift doctor explain <code> expands any of them into the full meaning and the remedy, and drift doctor codes lists every one this binary knows. Both work offline and without a session, which is exactly when you are holding one. A code is minted once and never reused or renumbered, so one pasted from a chat log a year old still resolves to the same failure.
Before the request lands
These happen on your machine or on the wire. No slice was touched.
- What you see
couldn't reach the Drift API (timed out). Is the platform up?- What it means
- The request left and nothing came back inside the timeout.
- What to do
- Check your own connection first. If that is fine, the platform is likely mid-restart, so try again in a minute.
- What you see
couldn't reach the Drift API. Is the platform up?- What it means
- DNS did not resolve, or the connection was refused outright.
- What to do
- Nothing reached Drift at all. A proxy or a firewall between you and
api.ondrift.euis the usual cause.
- What you see
Drift is temporarily unavailable — most likely brief maintenance. Your login is still valid; nothing to do but try again in a few minutes.- What it means
- The platform answered with a 502, 503 or 504. It is up but not serving.
- What to do
- Wait. Do not log out. Re-authenticating needs the same platform, so logging out here turns a short wait into a lockout.
- What you see
the platform is having trouble. That's on us; give it a moment and try again.- What it means
- A plain 500: the platform hit a fault handling the request. Not maintenance, and not caused by anything you did.
- What to do
- Retry once. If it keeps happening, check
status.ondrift.euand report it. This one is a bug, not a busy period.
- What you see
this machine has no copy of the Driftfile format yet, so it cannot be validated- What it means
drift file linthas never fetched the schema, so it has nothing to validate against.- What to do
- Run any online command once, such as
drift account loginordrift slice list, and it caches permanently at~/.drift/driftfile.schema.json.
"Unavailable" never names a component.
Your account and session
- Code
DRIFT-1001- What you see
your session expired. Run 'drift account login' to re-authenticate.- What it means
- Your token is no longer valid.
- What to do
drift account login.
- Code
- none
- What you see
invalid username or password.- What it means
- Only on
drift account loginitself. - What to do
- Check the credentials. There is no rate-limit lockout to wait out.
- Code
DRIFT-1002- What you see
you don't have permission to do that.- What it means
- You are authenticated, and this is not yours.
- What to do
- Usually a slice belonging to another account.
drift slice listshows what you can reach.
- Code
DRIFT-1013- What you see
that conflicts with existing state.- What it means
- You asked for something that collides with what already exists.
- What to do
- The message names the conflicting thing when the platform supplied one, most often a second free slice (one Hacker grant per account; a second is allowed, but priced) or a name already taken.
drift slice listshows what you have.
Deploying a project
Most of these are found offline, before anything is built or uploaded. drift file lint reaches all of them without an account.
- What it means
- Your Driftfile uses
${VAR}for something decided at deploy time, most oftenslice.name: ${ENV}-myappfor a staging/prod split, and the shell running the deploy never set it. - What to do
- Export the variable, add
--env(which also sets${ENV}) or--secret KEY=valuetodrift file apply, or put it in a.envfile next to the Driftfile.
- What it means
- An entry names no callable.
route,methodandhandlerare all required (orname,memoryandhandlerin the retired spelling). - What to do
- Add
handler:. See Write a function.
- What it means
- The handler is not in the element's folder. The error lists the callables that are there.
- What to do
- Usually a spelling or case difference. The message says so explicitly when the only difference is case.
- What it means
- Two files in one element declare the same handler. The generated entry point imports by name and cannot pick.
- What to do
- Rename one, or split them into separate elements.
- What it means
- Two entries have the same
name. The/apispace is shared across every element, so this collides wherever they live. - What to do
- Method is part of the identity, so
get:xbesidepost:xis fine; twopost:xis not.
- What it means
- An element has one dependency manifest and one runtime, so it cannot be two languages.
- What to do
- Move one language into its own folder under
atomic/and give those functions anelement:.
- What it means
- The manifest declares functions in a directory that holds no code.
- What to do
- Check
dir:/element:against where the handlers actually live.
- What it means
- The slice is contracted for M functions and already runs N.
- What to do
drift slice resizeto buy another slot, or remove a function you no longer need.
- What it means
- Some declared resource exceeds what the slice booked.
- What to do
- The message names the resource when the platform supplied one.
- What it means
- A
dir:points somewhere that is not on this machine. - What to do
- A schema cannot check paths; only your laptop can. Fix the path or drop the key and let the element own it.
- What it means
- The function isn't in this slice's shape yet.
drift file linthappily accepts a Driftfile naming it, because onlydrift slice resizeadds the slot on the slice itself. This is the one row heredrift file lintcannot catch offline. - What to do
drift slice resizeto add the slot, then deploy again.
drift file apply will not create a slice for you.
drift slice create instead of provisioning something you never priced. Make the slice first with drift slice create <name>. Apply never changes a slice's shape in either direction. Growing and shrinking both happen in the form, via drift slice resize.While your function runs
These reach the caller, not your terminal. Read them with drift atomic logs.
- What it means
- No function is registered at that method and path.
- What to do
- A function is identified by method and path, so
POST /api/itemsdoes not fall through to theget:itemshandler. Check thenamein your Driftfile.
- What it means
- The function's gate is
auth: apikeyand the request carried no valid key. - What to do
- See Authentication. Setting a key on a route forces
apikeywhatever the entry says.
- What it means
- The gate is a value the slice does not understand.
- What to do
- Only
noneandapikeyexist.drift file lintrefuses anything else offline, so this can only appear on a function deployed before that check existed.
- What it means
- Two unrelated things answer 429, and they are worth telling apart.
- What to do
- Either the slice-wide
rate_limitshed the request, or the function's memory pool had no room to admit another invocation. The first is a quota you set; the second means concurrent calls together exceeded what that function booked.
- What it means
- Your handler returned an error, panicked, or exceeded
function_timeout. - What to do
- An error or panic is caught and answered as 500 rather than crashing anything visibly. How far the damage is contained depends on the language: Go, Rust, Ruby and PHP each run a call in its own process, so a crash stays with that one invocation. Python and Node are different: one long-lived server per language holds every function written in it, so a crash severe enough to take that server down reaches every function sharing it, not only the one that failed.
- What it means
- The function was reached but produced no usable response, commonly a handler returning the wrong shape.
- What to do
- Return
(status, message, payload); Go adds a fourth headers value. See Write a function.
Secrets that are not there
A function receives only the secrets its own entry names. If drift.Backbone.Secret.Get("X") comes back empty or errors:
- Check
secrets:on that function's Driftfile entry. A secret the slice holds is still unreachable from a function that did not name it. - Check the value exists, with
drift backbone secret list. - Read it through the SDK, not the environment.
DRIFT_SECRET_Xexists only on the per-invocation subprocess path; Python and Node functions served by the persistent language server get theirs in the request envelope and no environment variable is set.
Adding a name to secrets: needs a redeploy. Changing a value does not, since the runner fetches on every call.
When none of this fits
drift file lint and drift file simulate answer most questions without deploying anything, and neither needs the platform to be healthy. If the message carries a DRIFT- code, drift doctor explain may already answer it, also offline. Otherwise, if it is not on this page, it came from the platform unchanged. Quote it verbatim when reporting, because the wording identifies which check produced it.