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 for the platform. 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. The messages about your Driftfile are the CLI's own, and they are on this page.
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 ends with the address of that code's section on this very page, like more: https://docs.ondrift.eu/troubleshooting/error-codes/#drift-1006. 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
- See the section for DRIFT-1007.
- What to do
- The same section says what to do.
- What you see
couldn't reach the Drift API. Is the platform up?followed by the underlying error in parentheses- What it means
- See the section for DRIFT-1006.
- What to do
- The same section says what to do.
- 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
- See the section for DRIFT-1012.
- What to do
- The same section says what to do.
- What you see
the platform is having trouble. That's on us; give it a moment and try again.- What it means
- See the section for DRIFT-1005.
- What to do
- The same section says what to do.
- What you see
this machine has no copy of the Driftfile format yet, so it cannot be validated- What it means
- The CLI prints this message without a code. See the section for DRIFT-1008, which
drift doctor explain 1008also prints. - What to do
- The same section says what to do.
The registry also names three failures that are not HTTP statuses: DRIFT-1009, DRIFT-1010 and DRIFT-1011. drift doctor explain expands each, and so does its section under Every code.
"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
- See the section for DRIFT-1001.
- What to do
- The same section says what to do.
- Code
- none
- What you see
invalid username or password.- What it means
- Only on
drift account loginitself. - What to do
- Check the credentials. Ten attempts a minute from one address are allowed; past that, the answer is
DRIFT-1014below.
- Code
- DRIFT-1002
- What you see
you don't have permission to do that.- What it means
- See the section for DRIFT-1002.
- What to do
- The same section says what to do.
- Code
- DRIFT-1003
- What you see
that resource wasn't found., or the platform's own reason when it sent one- What it means
- See the section for DRIFT-1003.
- What to do
- The same section says what to do.
- Code
- DRIFT-1013
- What you see
that conflicts with existing state.- What it means
- See the section for DRIFT-1013.
- What to do
- The same section says what to do.
- Code
- DRIFT-1014
- What you see
- the platform's reason, then
This clears by itself; try again in 60 seconds. - What it means
- See the section for DRIFT-1014.
- What to do
- The same section says what to do.
- Code
- DRIFT-1004
- What you see
this shape needs more functions than the plan allows, then the figures, such asatomic.functions: 3 of 3 used., then where to raise it- What it means
- See the section for DRIFT-1004.
- What to do
- The same section says what to do.
- Code
- DRIFT-1021
- What you see
- the platform's own reason, then a line giving the figure of the limit it hit, beneath the code line
DRIFT-1021 - What it means
- See the section for DRIFT-1021.
- What to do
- The same section says what to do.
A status on its own does not say which of these it is: the code is read from whether the body names a ceiling, not from 409, 413 or 429 alone. A 409 that names no ceiling is DRIFT-1013; one that does, such as the member cap, is DRIFT-1004 or DRIFT-1021.
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, and drift plan and drift apply run the same checks first.
A Driftfile error names the file and the position, Driftfile:12:5: <summary>: <detail>, and a file's errors are all printed at once, top to bottom, so one pass fixes them all. A failure to find the file at all reads no Driftfile in the current directory, followed by the path it looked in and a line naming drift file new, the command that writes one. Long messages are quoted here by their first sentence; the rest of each message explains the same thing at more length.
- What it means
- A
functionorworkerblock has nohandler. - What to do
- Add
handler = "GetItems". See Write a function.
- What it means
- Every function and worker states its own booking: it is the slot's pool and what it is billed at, so it has no default.
- What to do
- Add
memory = "32MiB". Once the function has served traffic,drift sizerewrites it from what the slice measured.
- What it means
- Sizes are a whole number of KiB, MiB or GiB.
64MBis refused rather than guessed at. - What to do
- Write
"64MiB".
- What it means
- A booking outside what a slot may hold.
- What to do
- Book between 8MiB and 256MiB (16MiB or more in a compiled language).
- What it means
- A compiled language (Go, Rust) carries a private runtime inside every invocation, and a Worker runs Go.
- What to do
- Raise the booking to
16MiBor more, or rundrift sizeagainst a deployed slice.
- What it means
- The handler is not in the backend'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 backend declare the same handler. The generated entry point imports by name and cannot pick.
- What to do
- Rename one, or split them into separate backends.
- What it means
- Two
functionblocks have the same method and route. A booking key is unique across the whole slice, not per backend, so this collides wherever they live. - What to do
- Method is part of the identity, so
GET /itemsbesidePOST /itemsis fine; twoGET /itemsis not.
- What it means
- A backend 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 declare its functions in abackendblock of that name.
- What it means
- The file declares functions in a directory that holds no code.
- What to do
- Check the backend's name and
diragainst where the handlers actually live.
- What it means
- A
dirpoints somewhere that is not on this machine. - What to do
- A schema cannot check paths; only your laptop can. Fix the path.
- What it means
- A value reads
env("MEM")and nothing sets it here. - What to do
- Set it in the terminal, with
--var MEM=..., or in a.envfile beside the Driftfile, as the message says.
- What it means
- A secret's
value, a function'sauth.api_keyand a site password are write-only. A literal would be a credential committed with the file, so it is refused, and so arevar.xandfile(). The message never prints the value. - What to do
- Write
env("NAME")and supply the value at apply time.
- What it means
- A
sliceorenvironmentblock still has abillingline. The shape decides: one inside the free slice can take one of your free slices, any other is priced. - What to do
- Delete the line.
drift plansays whether the slice would be free or priced, and why.
- What it means
- The same limit is set in two places.
- What to do
- Write it in one place.
- What it means
drift plan qa,drift apply qaor--env qanames an environment the file does not declare.- What to do
- Use one the message lists, or add an
environmentblock.
- What it means
- A
variablewith nodefaultthat the environment'svarsdoes not set. - What to do
- Give it a
default, or set it in the environment'svars.
- What it means
- A function is labelled with a method and route,
"POST /rpc", or withQUEUEand the queue it drains,"QUEUE orders". - What to do
- Fix the label.
- What it means
- A key the block does not take.
- What to do
drift file explain <block>lists what it does.
- What it means
- A second
sliceblock. - What to do
- Declare one slice per file, and use
environmentblocks for the others.
Applying has questions of its own. They are all asked, or refused, before anything is sent:
- What it means
- There is no terminal to ask the price, removal or data-loss questions, and none was answered.
- What to do
- Read the plan, then re-run with the flags listed.
- What it means
- The figure you approved is not the figure the platform quotes now.
- What to do
- Run
drift planagain and approve the new figure.
- What it means
- A
secret, anauthkey or a site password reads a variable nothing sets. The plan marks it!. - What to do
- Set it in the terminal, with
--var, or in a.envfile beside the Driftfile.
- What it means
- The new slice fits the free slice, and every free slice you may hold is taken. Idle cooldown lowers what an idle free slice costs, but it does not free its slot.
- What to do
- Empty one first (delete it, or give it a shape that is priced), or make this slice a priced one with
--approve-price <cents>, asdrift planquotes it.
- What it means
- A new slice fits the free slice, you have a free slot, and there is no terminal to ask
You have 2 of 3 free slices — make this the 3rd? - What to do
- Re-run with
--use-free-slice, or with--approve-priceto make it a priced slice.
- What it means
- The file grew a free slice past what the free slice grants.
drift applydoes not move a slice off the free tier yet, so nothing was applied. - What to do
- Make the shape fit again, or move the slice with
drift slice resize.
- What it means
drift apply plan.jsonapplies exactly the plan it recorded, and refuses when anything moved. Nothing was applied.- What to do
- Run
drift plan --out plan.jsonagain.
- What it means
- The platform refused the resize because the answers you gave no longer match.
- What to do
- Run
drift planagain.
drift apply creates the slice and resizes it.
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 the label in your Driftfile.
- What it means
- The function has an
authblock (or a key set withdrift atomic auth set) and the request carried no valid key. - What to do
- See Authentication. Setting a key on a route protects it whatever the file says.
- What it means
- The slice lists the networks it accepts in
allowin itsedgeblock, and the caller is outside all of them. The response carriesX-Drift-Refused-By: edge.allow. - What to do
- Add the caller's range, or call from an admitted network. See The IP allowlist.
- What it means
- A Canvas path behind the site gate, and no valid username and password.
/api/and/trigger/are never asked for it. - What to do
- Sign in at the browser's prompt, or send the credential as HTTP Basic auth. A
503 site authentication is unavailablemeans the slice's Deed could not check it; retry.
- What it means
- The slice passed its requests per minute,
rate_limit, and the router shed the request with{"error":"rate limit exceeded"}. - What to do
- Raise the limit, or send less. A function whose memory pool has no room for another invocation is a different answer,
503withX-Drift-Reason: FUNCTION-MEMORY, never a 429: see Limits and alerts.
- What it means
- The platform has suspended the slice, ahead of everything else the request would have met, including the allowlist, the rate limit and the gate. Nothing was dialled, and nothing was deleted.
- What to do
- See Acceptable use for why a slice gets suspended and how that gets lifted.
- What it means
- Your handler returned an error, panicked, or exceeded the slice's
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 block names. If drift.Backbone.Secret.Get("X") comes back empty or errors:
- Check
secretsin that function's block. A secret the slice holds is still unreachable from a function that did not name it. - Check the file declares it with a
secret "X" { value = env("X") }block insidebackbone, and that the variable was set when you randrift apply. The plan marks a secret whose variable is missing with!. - Check the value exists, with
drift backbone secret list. A secret the slice holds and the file does not name is a removal indrift plan, deleted if you agree to it. - 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.
Every code
The tables above show what the CLI prints and link each code to its section here. There is one section for every code, in order, generated from a copy of the registry that drift doctor explain reads, so a section says what drift doctor explain says. A retired code keeps its section, because a message from an older install can still name it.
DRIFT-1001
Your session has expired, so the platform refused the request.
Run drift account login and try again. Sessions are 12 hours; this is the ordinary way one ends.
Fix: drift account login
DRIFT-1002
The platform accepted your identity but refused the action.
The account is authenticated and lacks the permission for this operation. If it is meant to be your own slice, you may be on a different account than you think — drift slice list shows what this one actually has.
Fix: drift slice list
DRIFT-1003
The thing you named does not exist on the platform.
Check the spelling, and that your active slice is the one you mean — drift slice list shows what the account actually has.
Fix: drift slice list
DRIFT-1004
You have hit a quota on your plan.
The message names which one. Free a slot by deleting something you no longer need, or raise the limit. For a slice a Driftfile declares, raise it in the Driftfile and run drift apply: an apply makes the slice the shape the file says, so a limit raised on the resize form is undone by the next one. For any other slice, raise it on the form drift slice resize draws.
Fix: drift apply
DRIFT-1005
The platform failed while handling the request. This one is ours, not yours.
Nothing you changed caused it. Retry once; if it persists, the failure is on the platform side and status.ondrift.eu carries the per-component picture.
There is no command you can run for this one.
DRIFT-1006
The CLI could not reach the Drift API at all.
No response came back, so this is the network between you and the platform, or the platform being down. Check your connection first, then status.ondrift.eu.
There is no command you can run for this one.
DRIFT-1007
The request to the platform timed out.
The platform accepted the connection and did not answer in time. Retry; a deploy that timed out may still have landed, so check with drift plan before applying again.
Fix: drift plan
DRIFT-1008
This machine has no copy of the Driftfile format, so a Driftfile cannot be validated.
The platform defines the format and the CLI caches it on first contact. Run any online command once — drift account login or drift slice list — and it is cached permanently at ~/.drift/driftfile.schema.json.
Fix: drift slice list
DRIFT-1009
The Driftfile is not valid.
The message names the field and what it expected. drift file lint reports every problem at once, offline, which is faster than fixing them one deploy at a time.
Fix: drift file lint
DRIFT-1010
A compiled function booked less memory than its language runtime needs.
Go and Rust carry a private runtime inside every invocation, so they floor at 16MiB where the interpreted languages floor at 8MiB. Raise its memory in the Driftfile, or run drift size against a deployed slice to size it from what it actually holds.
Fix: drift size
DRIFT-1011
You are not logged in, so the CLI has no credential to send.
Run drift account login, or drift account signup if you do not have an account yet. This is different from an expired session (DRIFT-1001): there is no session on this machine at all.
Fix: drift account login
DRIFT-1012
The platform was briefly unavailable — a restart, a rollout, or something reshaping the slice underneath the request.
Wait a few seconds and run it again. Unlike DRIFT-1005 this CAN be something you just did: a resize restarts the slice's pod, so a deploy issued seconds after one hits a runner that is no longer there. If two commands were in flight at once, that is the likely story. status.ondrift.eu will usually show every component green, because nothing is broken.
There is no command you can run for this one.
DRIFT-1013
The thing you asked for conflicts with something that already exists.
The message names the conflicting thing. A second free slice is the common one — the free tier allows a single hacker slice per account, and a second slice of that shape is allowed but paid. Creating something whose name is taken is the other.
Fix: drift slice list
DRIFT-1014
The platform is limiting how often you can do this, and the limit clears by itself.
Wait for the time the message names, then run it again. Nothing needs freeing or buying: this is a rate limit, not a quota, and resizing a slice does not lift it. Logins and signups are limited per address, control-plane calls per account each minute, restarts per slice, and transfer offers per account each day. A retry before the time is up is refused again.
There is no command you can run for this one.
DRIFT-1015
The platform speaks a newer API version than this drift, and it answered not found to a request this drift made.
The platform states the API version it speaks on every reply. When that is ahead of the one this drift was built for, a request for a path the platform no longer serves comes back as a plain not found. drift upgrade installs the release that speaks the platform's version. If the same request still says not found after upgrading, the thing you named does not exist: see DRIFT-1003.
Fix: drift upgrade
DRIFT-1016
The platform rejected the request as invalid.
The message names what the platform did not accept: a field, a value or a format. Change what it names and run the command again, because the same request is refused the same way every time. No single command fixes it, since what to change is in the message.
There is no command you can run for this one.
DRIFT-1017
The username or password was refused.
Check the username and the password and try again; a mistyped password is by far the commonest cause. This is not an expired session (DRIFT-1001): there is no session yet to renew, so logging in again is the command that just failed. If the password is forgotten, drift account reset-password starts a reset.
Fix: drift account reset-password
DRIFT-1018
The platform ended your session on purpose.
A refresh arrived from a different machine than the one you logged in on, or with a token that had already been used. Drift treats that as a stolen session file and cuts every session on the account. Run drift account login to get back in. If that was not you on another machine, also run drift account reset-password, because someone else may hold the old session file. Unlike an ordinary expiry (DRIFT-1001), logging in alone is not enough when you did not end the session yourself.
Fix: drift account login
DRIFT-1019
The access token in DRIFT_TOKEN was refused.
The platform answered and said no: the token was revoked or has expired, or the variable holds something that is not a Drift token, which starts with drift_pat_. drift account token list shows the tokens the account holds, and drift account token create mints a replacement to put in DRIFT_TOKEN. This is different from DRIFT-1011, where no credential was found at all. Both commands are four words, so no single command is named here.
There is no command you can run for this one.
DRIFT-1020
The connection to the platform failed in a way the CLI does not recognise.
The text before this code's line is the error exactly as the connection reported it. A certificate that could not be verified usually means a proxy or a security product on this network is re-signing the traffic, and the fix is to trust its certificate on this machine or to use another network. A response that ended early means the connection dropped in the middle of the answer, and running the command again usually succeeds. Unlike DRIFT-1006, where nothing answered, and DRIFT-1007, where the answer took too long, something answered here and the exchange broke. If it repeats, send the whole message, this code included, to support. No single command fixes it.
There is no command you can run for this one.
DRIFT-1021
The platform's own limit stopped this, and no change to your slice raises it.
The message names the limit that was hit and the last line gives its figure. Drift sets this limit itself and it is the same for everyone, so it is not a quota on your plan and nothing about your slice raises it. Bring what you hold or send under it instead: a smaller file, value or statement, fewer items in one request, or one fewer member, whichever the message names. Then run the command again. No command lifts the limit, so none is named here.
There is no command you can run for this one.
DRIFT-1022
A part of the platform is not operational.
The platform's own status feed reports at least one component as degraded or down, and the line that carries this code names it. This is the platform and not your project, so nothing in your Driftfile or your code causes it and nothing you can run repairs it. Wait, then run drift doctor again; status.ondrift.eu shows the same components. A command that failed while a component was down is worth running again once it is back.
There is no command you can run for this one.
When none of this fits
drift file lint answers most questions without deploying anything or touching the network, and drift plan adds the live slice and still changes nothing. 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.