drift Docs
Pages
drift Docs
Start
What is Drift?
The tour, if you are new here.
Use cases
Whether Drift does your thing.
Getting started
Nothing to deployed, in one command.
Architecture
How a slice is put together.
What it costs
The free grant, four unit prices, two rules.
Moving off Azure
Estimate, snapshot and transform a resource group.
Build
Canvas
Static sites, same origin as your API.
Tools
Operate
Auth
Route gates, API keys and your account.
Teams
More than one person on one account.
Security
Boundaries, sandboxing and hardening.
Troubleshooting
Error codes
What went wrong, and what to do about it.
Legal
Acceptable use
What a slice may not be used for.
Data processing
The DPA, and every sub-processor.

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 seeWhat it meansWhat to do
  • 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.
  • none
    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 1008 also 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.

A slow store, a restart and a configuration change are the same event from outside, and which one it was is Drift's problem rather than yours. The message says to wait because waiting is the whole of the correct response.

Your account and session

CodeWhat you seeWhat it meansWhat to do
  • 401
    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.
  • 401
    Code
    none
    What you see
    invalid username or password.
    What it means
    Only on drift account login itself.
    What to do
    Check the credentials. Ten attempts a minute from one address are allowed; past that, the answer is DRIFT-1014 below.
  • 403
    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.
  • 404
    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.
  • 409
    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.
  • 429 with a wait
    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.
  • 402, 409, 413, 422 or 429
    Code
    DRIFT-1004
    What you see
    this shape needs more functions than the plan allows, then the figures, such as atomic.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.
  • 402, 409, 413, 422 or 429
    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 meansWhat to do
  • Driftfile:5:3: Missing handler: function "GET /items" names the callable that serves it
    What it means
    A function or worker block has no handler.
    What to do
    Add handler = "GetItems". See Write a function.
  • Driftfile:5:3: Missing memory: function "GET /items" books its memory
    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 size rewrites it from what the slice measured.
  • Driftfile:7:14: Not a size: function "GET /items": memory "64MB" is not a size
    What it means
    Sizes are a whole number of KiB, MiB or GiB. 64MB is refused rather than guessed at.
    What to do
    Write "64MiB".
  • Driftfile:7:14: Memory out of range: function "GET /items" books 512MiB; a slot books from 8MiB to 256MiB
    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).
  • a compiled function or worker needs at least 16MB, and 1 of these book less, or Below the compiled floor: worker "w" books 8MiB
    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 16MiB or more, or run drift size against a deployed slice.
  • function "get:items": the Driftfile declares a function served by "getItems", and no such callable is in <dir>
    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.
  • function "get:items": "GetItems" is declared in 2 files in <dir>
    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.
  • the function "get:items" is declared 2 times (in the backend default)
    What it means
    Two function blocks 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 /items beside POST /items is fine; two GET /items is not.
  • backend "default": <dir> mixes languages (python in b.py, go in items.go)
    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 a backend block of that name.
  • backend "empty": no source files in <dir>
    What it means
    The file declares functions in a directory that holds no code.
    What to do
    Check the backend's name and dir against where the handlers actually live.
  • Driftfile:8:11: Not found: function "GET /items": dir: nowhere does not exist, or site "/": dir: nosuch does not exist
    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.
  • Driftfile:7:14: Error in function call: Call to function "env" failed: environment variable MEM is not set
    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 .env file beside the Driftfile, as the message says.
  • Driftfile:9:17: A secret is a reference: function "GET /items": auth.api_key is write-only and must be written env("NAME")
    What it means
    A secret's value, a function's auth.api_key and a site password are write-only. A literal would be a credential committed with the file, so it is refused, and so are var.x and file(). The message never prints the value.
    What to do
    Write env("NAME") and supply the value at apply time.
  • Driftfile:2:3: billing is gone: a Driftfile no longer says how a slice is paid for. Delete this line: ...
    What it means
    A slice or environment block still has a billing line. 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 plan says whether the slice would be free or priced, and why.
  • Driftfile:8:16: Written twice: edge.rate_limit and limits.requests_per_minute are one limit
    What it means
    The same limit is set in two places.
    What to do
    Write it in one place.
  • Driftfile:1:1: Unknown environment: there is no environment "qa": the file declares staging
    What it means
    drift plan qa, drift apply qa or --env qa names an environment the file does not declare.
    What to do
    Use one the message lists, or add an environment block.
  • Driftfile:4:1: Variable has no value: variable "x" has no value here
    What it means
    A variable with no default that the environment's vars does not set.
    What to do
    Give it a default, or set it in the environment's vars.
  • Driftfile:5:9: Not a function trigger: function "FETCH /items"
    What it means
    A function is labelled with a method and route, "POST /rpc", or with QUEUE and the queue it drains, "QUEUE orders".
    What to do
    Fix the label.
  • Driftfile:3:3: Unsupported argument: An argument named "colour" is not expected here
    What it means
    A key the block does not take.
    What to do
    drift file explain <block> lists what it does.
  • Driftfile:4:1: Duplicate slice block: one file declares one slice
    What it means
    A second slice block.
    What to do
    Declare one slice per file, and use environment blocks for the others.

Applying has questions of its own. They are all asked, or refused, before anything is sent:

What it meansWhat to do
  • nothing was applied: this plan needs an answer to each of these, and none was given, then flags such as --approve-price 768 and --approve-remove "function GET /bench"
    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.
  • the platform quotes €7.68 a month for this shape, not the €5.00 agreed to with --approve-price; nothing was applied
    What it means
    The figure you approved is not the figure the platform quotes now.
    What to do
    Run drift plan again and approve the new figure.
  • nothing was applied: secret STRIPE_KEY reads $STRIPE_KEY, which is not set
    What it means
    A secret, an auth key 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 .env file beside the Driftfile.
  • nothing was applied: the free tier is 3 slices per account and you hold all 3:, then the names
    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>, as drift plan quotes it.
  • nothing was applied: this plan needs an answer ... with --use-free-slice among the flags
    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-price to make it a priced slice.
  • slice "x" is a free slice and its shape no longer fits the free slice (...), which would make it a priced one
    What it means
    The file grew a free slice past what the free slice grants. drift apply does 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.
  • the Driftfile changed after the plan was made (or slice "x" changed after the plan was made, or this plan no longer asks what the recorded one did)
    What it means
    drift apply plan.json applies exactly the plan it recorded, and refuses when anything moved. Nothing was applied.
    What to do
    Run drift plan --out plan.json again.
  • The slice changed after the plan was made, or the platform asks something the plan did not show. Nothing was resized
    What it means
    The platform refused the resize because the answers you gave no longer match.
    What to do
    Run drift plan again.

drift apply creates the slice and resizes it.

It does both from the Driftfile's shape, so there is no slice to make first. What it asks before it does is the price, each removal and each loss of data, and a plan shows all of them without changing anything.

While your function runs

These reach the caller, not your terminal. Read them with drift atomic logs.

What it meansWhat to do
  • 404
    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/items does not fall through to the GET /items handler. Check the label in your Driftfile.
  • 401
    What it means
    The function has an auth block (or a key set with drift 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.
  • 403 with code EDGE-ALLOW
    What it means
    The slice lists the networks it accepts in allow in its edge block, and the caller is outside all of them. The response carries X-Drift-Refused-By: edge.allow.
    What to do
    Add the caller's range, or call from an admitted network. See The IP allowlist.
  • 401 with WWW-Authenticate: Basic
    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 unavailable means the slice's Deed could not check it; retry.
  • 429
    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, 503 with X-Drift-Reason: FUNCTION-MEMORY, never a 429: see Limits and alerts.
  • 503 with {"error":"this slice is suspended"}
    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.
  • 500
    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.
  • 502
    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:

  1. Check secrets in that function's block. A secret the slice holds is still unreachable from a function that did not name it.
  2. Check the file declares it with a secret "X" { value = env("X") } block inside backbone, and that the variable was set when you ran drift apply. The plan marks a secret whose variable is missing with !.
  3. Check the value exists, with drift backbone secret list. A secret the slice holds and the file does not name is a removal in drift plan, deleted if you agree to it.
  4. Read it through the SDK, not the environment. DRIFT_SECRET_X exists 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.