Errors & fixes

Every Regixo error carries a stable code a script or regixo doctor can act on, a human message, and — where there is one — a fix. The codes are a contract: they are never renamed, only added.

Machine output puts the code and remedy under error.code and error.fix; regixo help --json lists the whole registry. The tables below carry the exact message and fix strings for each code, grouped by where you meet them.

Agent rails These codes exist so an autonomous agent (or your CI) reads a fact instead of guessing. regixo doctor resolves and probes your setup, then prints the matching fix.

Setup & config

Code	What it means	Fix
`NODE_VERSION_UNSUPPORTED`	This Node version is older than the 22.18 floor Regixo needs.	`nvm install 22` (or upgrade Node with your installer), then run the command again.
`CONFIG_NOT_FOUND`	No `regixo.yml` configuration was found.	Copy `regixo.yml.example` to `regixo.yml` in this folder (it is read before `.regixo/regixo.yml`) and edit it, or set `REGIXO_CONFIG` to its path.
`CONFIG_INVALID`	`regixo.yml` could not be parsed.	Check the YAML syntax against `regixo.yml.example`; run `regixo doctor`.
`CONFIG_INPUT_INVALID`	The `regixo config` input was invalid.	Usage: `regixo config` to view settings, or `regixo config catalog-only <on\|off>` to change one.
`PORT_IN_USE`	The server port is already in use.	Stop the other process, or pass `--port` (or set `REGIXO_HTTP_PORT` for `open` / `REGIXO_CLAIM_PORT` for `serve-claim`) to a free port.
`SCHEMA_MIGRATION_REQUIRED`	The local store schema is out of date.	Run the store migration, or delete the local `.regixo` store to re-scan from scratch.
`DATA_KEY_INVALID`	`REGIXO_DATA_KEY` is set but is not a 32-byte key.	Generate one with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"` and set `REGIXO_DATA_KEY` to it (base64 or 64-char hex).
`CONFIRM_REQUIRED`	This permanently deletes something, so it was not done.	If you really want this, run the same command again with `--yes` on the end. It cannot be undone.

Sources

Code	What it means	Fix
`NO_SOURCES`	No sources are configured in `regixo.yml`.	Add at least one source (id, kind, driver, connectionRef) — see `regixo.yml.example`.
`NO_SOURCE_DETECTED`	No data source was found to scan (no source is connected yet).	Set `DATABASE_URL=postgres://…` and re-run `regixo start`, or run `regixo add postgres`.
`ADD_INPUT_INVALID`	The `regixo add` input was invalid.	Usage: `regixo add postgres --ref DATABASE_URL --label "App DB" [--region eu-central-1] [--role controller] [--yes]`.
`CONNECTOR_INPUT_INVALID`	The `regixo connectors` input was invalid.	Usage: `regixo connectors list`, `regixo connectors new <name>`, or `regixo connectors --skill` (the agent playbook). A name may only use letters, digits, - and _, and can’t be a built-in kind.
`CONNECTOR_EXISTS`	A connector file with that name already exists.	Pick another name, edit the existing file in `regixo-connectors/`, or pass `--force` to overwrite it.
`SOURCE_NOT_FOUND`	No configured source with that id.	List ids with `regixo sources`, then `regixo sources remove <id>`.
`SOURCE_UNREACHABLE`	A configured source could not be reached.	Check the host/port and that the source is running, then `regixo test <id>`.
`SECRET_UNRESOLVED`	A required secret could not be resolved.	Set the source’s connection env var (or `REGIXO_SECRET_<ref>`) — never in `regixo.yml`.
`SECRET_PLACEHOLDER_UNREPLACED`	The connection variable still holds the placeholder Regixo wrote, so there is no real credential to connect with yet.	Open `.env`, replace `<PASTE-YOUR-TOKEN-HERE>` with your own password, token or API key, then re-run. `regixo doctor` names the variable.
`DRIVER_MISSING`	No connector driver is registered for this source kind.	Enable/install the connector for this source kind.
`MAP_NOT_FOUND`	No local map (`index.db`) was found to open.	Run `regixo start` first to scan your sources into the local catalog.
`STALE_CATALOG`	The catalog is stale — `regixo invite` would ship the LAST scan, not your database as it is now.	Re-run `regixo start` to refresh the catalog (it does NOT read the DB live), then `regixo invite`. To ship the current catalog anyway, pass `--yes`.

Compliance & catalog

Code	What it means	Fix
`ROPA_INPUT_INVALID`	The RoPA annotation could not be applied.	Use `regixo annotate list` to see the activity keys + fields, then `regixo annotate set <activityKey> <field> <value> [--confirm]`.
`SIGNER_REQUIRED`	Confirming a legal field records WHO confirmed it, and no signer identity is set (`REGIXO_SIGNER_EMAIL`).	Set `REGIXO_SIGNER_EMAIL` to the person on your compliance team making this call (e.g. `REGIXO_SIGNER_EMAIL=dpo@yourco.eu`), then re-run with `--confirm`. Without `--confirm` the answer saves as a draft fill — no signer needed.
`SIGNER_NAME_REQUIRED`	A signature needs a person’s name — an email address on its own isn’t enough.	Set `REGIXO_SIGNER_NAME` to the name of the person signing (and `REGIXO_SIGNER_ROLE` to their role, e.g. "Data Protection Officer"). A regulator reading this record has to see who took responsibility for it, not an inbox.
`CONTROLLER_REQUIRED`	Your company’s name or a reachable contact is missing, so the official version can’t be created yet (the GDPR record must say which company is responsible and how to reach it).	Easiest: fill it in on the claim page before you unlock. (Or your engineer can add it to `regixo.yml` under "controller: name / contact" and re-run `regixo start`.)
`ROPA_NONE_UNCONFIRMED`	Not saved — “None” closes this field as “does not apply”, a legal confirmation.	Re-run with `--confirm` to record it (`REGIXO_SIGNER_EMAIL` names who makes the call), or give the actual values instead.
`OPEN_LEGAL_CALLS`	This record still has open legal calls, and sealing over them was not acknowledged.	Answer them (`regixo annotate set … --confirm`, or the claim page) — the stronger record. To seal with them flagged as open, re-run with `--seal-with-open-calls`; the seal records the acknowledgment.
`ROPA_CONFIRM_UNATTRIBUTED`	A confirmed legal answer in this file names no one who confirmed it, so the whole import was refused — confirmation is a named human act.	Re-export the catalog from the machine where the field was confirmed (`regixo catalog export` always carries who confirmed it), or add that row’s `by` in the file, then re-run the import.
`DORA_INPUT_INVALID`	The DORA input could not be applied.	Use `regixo dora import <tableCode> <file.csv>` (header row + data rows) or `regixo dora set <tableCode> <rowKey> <field> <value>`.
`DORA_NOT_SUBMITTABLE`	The DORA register did not pass validation against the regulation's table structure and datapoint formats, so no xBRL-CSV was produced.	Fix the malformed datapoint(s) named above (e.g. an LEI is 18 alphanumeric characters followed by 2 numeric check digits, uppercase), then re-run `regixo dora export`.
`TERMS_NOT_ACCEPTED`	Sealing an official record requires accepting the customer agreement, and it was not accepted.	Tick "I accept the agreement" on the seal page (or pass the acceptance in the API). The agreement version is set by the vendor (`REGIXO_TOS_VERSION`); when unset, no acceptance is required.
`CLASSIFY_INPUT_INVALID`	To correct a column, name the column and say what it is — one of: personal, special, criminal, or not.	"personal" = personal data · "special" = sensitive data (health, religion… Art. 9) · "criminal" = offence data (Art. 10) · "not" = not personal. Find a column id with `regixo describe list`, then `regixo classify set <columnId> personal`. Undo with `regixo classify clear <columnId>`.
`DESCRIBE_ENTITY_UNKNOWN`	No dataset or column with that id.	Run `regixo describe list` (or `regixo status`) to see the ids, then `regixo describe draft <id>`.
`LINEAGE_ENDPOINT_UNKNOWN`	A lineage edge needs two datasets that exist in the map.	Check both ids with `regixo describe list`, then `regixo lineage add <fromDatasetId> <toDatasetId>`.
`LINEAGE_EDGE_NOT_REMOVABLE`	Only human-asserted edges can be removed; dbt/automatic edges are regenerated by scans.	Run `regixo lineage list --origin user` to see removable edges, then `regixo lineage remove <edgeId>`.
`GLOSSARY_TERM_UNKNOWN`	That glossary action needs a term (and a definition, to set one).	Use `regixo glossary set <term> <definition> [--datasets id,id]`, or `regixo glossary list`.
`CATALOG_FILE_INVALID`	That file is not a Regixo team catalog, so nothing was imported.	Point the import at a file written by `regixo catalog export` — JSON with "format": "regixo-catalog" and an integer "version". If the file was hand-edited, the detail above names the first broken part.
`CATALOG_VERSION_UNSUPPORTED`	This team catalog was exported by a newer Regixo than the one running here, so nothing was imported.	Upgrade Regixo on this machine (for example `npx regixo@latest start`), then re-run the import. The file itself is fine.
`EVIDENCE_HASH_MISMATCH`	The evidence bundle failed verification — an artifact’s content no longer matches its manifest fingerprint.	The file was changed after it was generated (the ✗ lines above name which parts). Fetch the original bundle, or regenerate a fresh one with `regixo evidence`.

Portal & sync

Code	What it means	Fix
`INVITE_NOT_FOUND`	No invite snapshot was found to serve.	Run `regixo invite --no-upload` first — it drafts the record and writes the snapshot without sending anything. Then run `regixo serve-claim` to read it, and `regixo invite` when it reads right.
`UPLOAD_NOT_CONFIRMED`	The upload to the portal needs explicit confirmation, and there is no terminal to ask on.	Re-run `regixo invite --yes` to confirm the metadata-only upload (the preview is printed first), or `regixo invite --no-upload` to stay fully local.
`INVITE_RECIPIENT_REQUIRED`	This invite would upload with no recipient — an unbound claim link lets anyone holding it become the record’s admin.	Pass `--email <their-address>` to lock the claim link to your compliance contact (recommended), or `--unbound` to send it unbound on purpose.
`PORTAL_UNREACHABLE`	Could not reach the portal to upload the draft snapshot.	Re-run — the portal or your connection may be briefly down. If you set `REGIXO_PORTAL_URL` (a tunnel or self-host address), check that host is up.
`PORTAL_NOT_INSTALLED`	Not an error — this is the FREE build. Official export + attestation are the PAID step, so they are not included here.	When you want them, unlock at `https://app.regixo.com` (forward your `regixo invite` link). Free stays free forever.
`PORTAL_NOT_READY`	This hosted portal cannot sign a record, so it refused to start.	A public portal must be able to sign a record before it takes anyone’s money. Generate the signing key, publish its public half, and set the variable named in the message. Then start it again.
`INGEST_UNAUTHORIZED`	The portal refused the upload — it requires an ingest token.	Set `REGIXO_INGEST_TOKEN` to the token the portal operator configured, then re-run `regixo invite`.
`INGEST_RATE_LIMITED`	The portal rate-limited this upload (too many uploads from this address).	Wait an hour, then re-run `regixo invite` and forward the FRESH PDF.
`SNAPSHOT_TOO_LARGE`	The portal refused the snapshot — it exceeds the 5 MB upload cap.	A metadata-only snapshot this large is unusual — check the map size (`regixo status`); if your estate is genuinely that big, contact the vendor.
`SYNC_FAILED`	Metadata sync to the portal failed.	Check `REGIXO_PORTAL_URL` (is the host/tunnel up?) and `REGIXO_SYNC_TOKEN`; a revoked pairing needs a fresh token — an admin generates one under "Connect a machine" on your claim page. (A superseded claim fails as `CLAIM_NOT_SYNCABLE` instead.)
`SYNC_MISCONFIGURED`	A portal address is set but the machine token is missing — the push was skipped.	Set `REGIXO_SYNC_TOKEN` (an admin generates it under "Connect a machine" on your claim page); the address defaults to `app.regixo.com`, so the token is all most setups need. Or unset `REGIXO_PORTAL_URL` for a purely local setup. It starts `rgx_sync_` — never the licence key (`rgx_live_`).
`SYNC_UNAUTHORIZED`	The portal rejected the machine token — it is revoked, mistyped, or belongs to a different record.	An admin generates a fresh token under "Connect a machine" on your claim page; set it as `REGIXO_SYNC_TOKEN` on this machine. `regixo doctor` checks the pairing end to end.
`CLAIM_NOT_SYNCABLE`	The claim this machine pushes to was superseded or removed — the push has nowhere to land.	Re-run `regixo invite` for a fresh claim link, then pair this machine again with a token generated on the NEW claim ("Connect a machine").
`WEBHOOK_FAILED`	The change-summary webhook could not be delivered (the local re-scan completed and stands).	Check the `--webhook` URL is reachable from this machine, then re-run `regixo watch --webhook <url>` to retry the delivery.
`DORA_PULL_FAILED`	Could not pull the claim-side fills from the portal.	Check the claim token is correct and the portal is reachable — the pull uses the address on your recorded claim link automatically; `REGIXO_PORTAL_URL` overrides it. The same link you forwarded with `regixo invite` carries the token.
`SEAL_PULL_FAILED`	Could not pull the sealed artifacts from the portal.	Check the claim token is correct and the portal is reachable — the pull uses the address on your recorded claim link automatically; `REGIXO_PORTAL_URL` overrides it. `regixo status` shows whether the record is sealed at all.
`LICENCE_MISSING`	No unlock key was given, so there’s nothing to unlock with.	Easiest: unlock in the portal. (Or, for the command line, your engineer can set `REGIXO_LICENCE_KEY` to the key from your unlock email.)
`LICENCE_INVALID`	That unlock key doesn’t look right, so we couldn’t unlock.	Easiest: unlock in the portal instead. If you’re using the key, re-copy it exactly from your unlock email (it’s easy to miss a character).
`LICENCE_EXPIRED`	Your unlock has expired, so the record is back to a draft for now.	Renew to bring back the official, signed version. The portal shows your renewal options.
`LICENCE_REVOKED`	This unlock key has been turned off, so it can’t be used.	Contact Regixo for a replacement key. Anything already signed stays valid — nothing is deleted.
`LICENCE_TENANT_MISMATCH`	This unlock key belongs to a different record, so it won’t unlock this one.	Use the key that came with THIS record’s unlock email, or unlock from this record’s claim link in the portal.
`CLAIM_NOT_FOUND`	No live claim was found for that token (unknown, or replaced with no recorded successor).	List claims with `regixo admin tenants`; for a replaced claim, resend the successor token shown there.
`MAIL_NOT_CONFIGURED`	This portal has no email delivery configured, so the message cannot be sent.	Set `REGIXO_SENDGRID_API_KEY` + `REGIXO_MAIL_FROM` (or `REGIXO_SENDMAIL_CMD`), or run with `REGIXO_DEV_MODE=1` to log instead of sending.
`ADMIN_INPUT_INVALID`	The admin subcommand is missing or has invalid inputs.	Run `regixo admin help` (or `regixo help admin`) for the full command list and the flags each needs.
`ADMIN_NOT_CONFIRMED`	This is a destructive admin action and was not confirmed.	Re-run with `--yes` to confirm (agent/headless), or answer the prompt at an interactive terminal.
`ADMIN_ENV_INCOMPLETE`	This admin command needs the portal’s own settings, and they are not loaded.	Run it through the `regixo` command on the portal machine — that loads them for you. If you are calling the CLI directly, load them first: `set -a; . <your portal env file>; set +a`

app.regixo.com — the address regixo invite uploads to, and the one the unlock fixes name — is not switched on yet: public hosting is a launch gate, wired and offline-tested. Regixo has not launched. The fixes above name the destination it will answer on; until then, set REGIXO_PORTAL_URL to a portal you can reach, or stay local with regixo invite --no-upload.

Agents & API

Code	What it means	Fix
`INVALID_PARAM`	A required parameter is missing or not valid.	The detail names the usage — check `regixo help <command>` (e.g. `regixo search <words…>` needs the words to search for).
`DATASET_NOT_FOUND`	`No dataset with id "…".` — the id does not exist in this catalog.	List the ids the API serves at `GET /api/v1/datasets`, or call the `search_datasets` tool. An id reads `source/schema/table`, for example `app-db/public/users`.
`ENDPOINT_NOT_FOUND`	`No GET endpoint at /api/v1/… on this API.` — a path (or method) the read API does not serve.	The `404` body lists every endpoint this API serves; `GET /api/v1` returns the same list.

INVALID_PARAM is shared with the read API: /api/v1 answers a malformed query parameter with a 400 carrying this same code and a param field naming the culprit, so the CLI and the API speak one vocabulary. CLAIM_NOT_FOUND is likewise returned by the read API for an unknown or superseded claim. DATASET_NOT_FOUND and ENDPOINT_NOT_FOUND belong to the agent surface only — the read API and the regixo mcp tools return them, in one agreed shape across both. They are not in the CLI error registry, so regixo help --json does not list them and no regixo command exits with either.

Your next step A code or a term you do not recognise? The plain-English meaning of every word Regixo uses — RoPA, activity, Art. 9, DORA — is on the Glossary →.

← Back

Command reference

Glossary