Reference
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. |
CONTROLLER_REQUIRED |
Your company name is missing, so the official version can’t be created yet (the GDPR record must say which company is responsible). | Easiest: type your company name 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_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 first to produce the claim snapshot + PDF. |
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. |
PORTAL_UNREACHABLE |
Could not reach the portal to upload the draft snapshot. | Check REGIXO_PORTAL_URL (is the host/tunnel up?), then re-run regixo invite and forward the FRESH PDF — this run’s PDF has no live link (claim tokens are issued by the portal). |
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. |
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 or superseded pairing needs a fresh token from the portal Team card ("Connect a machine"). |
SYNC_MISCONFIGURED |
A portal address is set but the machine token is missing — the push was skipped. | Set REGIXO_SYNC_TOKEN (mint it on the portal Team card → "Connect a machine"); 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. |
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 (REGIXO_PORTAL_URL). 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 (REGIXO_PORTAL_URL). 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. |
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). |
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.