Error messages
Every error code DT Edge Platform surfaces, what it means, where to look next. Codes are stable strings — search this page when one shows up.
License gating
| Code | Where you see it | Means | Next |
|---|---|---|---|
LICENSE_MISSING | Toast on every action; landing page | No license loaded | Admin uploads — see How-to: upload license |
LICENSE_INVALID | Toast + License page red badge | Verification failed; reason on hover | Match the reason against License invalid runbook |
LICENSE_GRACE_READONLY | Toast on mutations | License expired, in grace; reads pass, mutations 503 | Renew before grace ends |
LICENSE_FINGERPRINT_MISMATCH | License upload | The license's --bind doesn't match this cluster | Get the new fingerprint, re-issue |
LICENSE_WRONG_PRODUCT | License upload | Minted with --product provisioner | Re-issue with --product dtedge |
LICENSE_SCHEMA_TOO_NEW | License upload | Newer schema than this DT Edge Platform build supports | Upgrade DT Edge Platform image first |
LICENSE_CLOCK_ROLLBACK | Server log + License page | Host clock went backwards | Fix timedatectl set-ntp true, restart pods |
FLEET_QUOTA_EXCEEDED | Toast on install / edge create | Operation would push over fleet cap | Handle fleet quota exceeded |
Auth + session
| Code | Means | Next |
|---|---|---|
INVALID_CREDENTIALS | Wrong email / password (login) or wrong current password (change-password) | Try again |
2FA_REQUIRED | Password OK; need TOTP code | Enter the 6-digit code |
INVALID_2FA_CODE | TOTP wrong | Check phone clock; try again |
TOKEN_EXPIRED | JWT past exp | Re-login |
INVALID_TOKEN | Signature mismatch (JWT_SECRET rotated server-side) | Re-login |
USER_DEACTIVATED | Your account is is_active=false | Ask admin |
USER_NOT_FOUND | API key references a user that's been deleted | Re-mint the API key |
2FA_REQUIRED (post-login) | Server policy requires 2FA but you haven't enrolled | Setup wizard appears in the login flow |
RBAC
| Code | Means | Next |
|---|---|---|
permission denied | Casbin enforce returned false | Your role doesn't grant this; ask admin to update your role or use a different one |
not a member of this organization | URL's :org_id not in your memberships | Switch org via the selector |
super admin access required | The endpoint is locked to super-admins | Ask a super-admin to do it |
Validation
| Code | Means |
|---|---|
INVALID_PAYLOAD | Request body didn't parse (typo in YAML, malformed JSON) |
INVALID_BASE64_KUBECONFIG | The kubeconfig you pasted isn't valid base64 |
INVALID_SETTING_KEY / INVALID_SETTING_VALUE | Admin → Settings save: unknown key or invalid value for it |
TELEMETRY_ID_REQUIRED / TELEMETRY_ID_TAKEN | Edge update: telemetry_id empty or already in use by another edge |
Edge instance
| Code | Means |
|---|---|
EDGE_INSTANCE_NOT_FOUND | The edge ID isn't yours or doesn't exist |
EDGE_OPERATION_IN_PROGRESS | Another op against this edge is in flight |
FAILED_ENCRYPT_KUBECONFIG | Server-side encryption error; ENCRYPTION_KEY env may be misconfigured |
PUBLIC_RESOURCE_NOT_LICENSED | Calling a public/admin endpoint whose MaxPublic* cap is 0 — feature off in this license |
Helm
| Code | Means |
|---|---|
OPERATION_IN_PROGRESS | Release is locked by a running op; wait |
RELEASE_OWNERSHIP_FORBIDDEN | On a public edge, this release was installed by another org; only that org can upgrade/uninstall |
PROTECTED_NAMESPACE | You tried to install into kube-system / cert-manager / DT Edge Platform / etc. |
REGISTRY_UNREACHABLE_VERSION_BUMP | Smart upgrade tried to pull a new version but registry is down. Pin to the current version (no version change → falls back to stored chart) |
Backup locations
| Code | Means | Next |
|---|---|---|
BACKUP_LOCATION_NOT_FOUND | The backup location was deleted or isn't visible to your org | Pick another location; backups already stored there remain restorable |
BACKUP_LOCATION_UNAVAILABLE | The S3 target is unreachable from the edge | Check endpoint, credentials and CA certificate; run the location's Test action (Organizations → Backup Locations) |
BACKUP_LOCATION_NOT_VALIDATED | The location couldn't be validated in time (test can take up to ~90s) | Check that Velero is healthy on the edge, then re-test |
Alarms
| Code | Means |
|---|---|
GRAFANA_NOT_CONFIGURED | system_settings missing the central Grafana URL/creds |
NO_EDGES_IN_SCOPE | The active org has no edges to scope the alarm to |
INVALID_PROMQL | Parser error; message includes position |
FORBIDDEN_LABEL_<NAME> | Your query references a reserved label (telemetry_id, dtedge_org_id, …); strip it — backend injects |
ALARM_NOT_FOUND | Rule UID isn't yours or doesn't exist |
GRAFANA_*_FAILED | Upstream Grafana API call failed (network, 5xx) |
Provisioner integration
| Code | Means |
|---|---|
PROVISIONER_NOT_CONFIGURED | Admin → Settings missing provisioner_url / admin_key |
PROVISIONER_UNREACHABLE | Network timeout to upstream Provisioner |
NODES_MISSING_SSH | Destroying an upstream cluster needs SSH creds the row doesn't have |
Operations
| Code | Means |
|---|---|
OPERATION_NOT_FOUND | Operation ID is wrong or it's been deleted |
OPERATION_NOT_RETRIABLE | You tried to retry an op that isn't in failed state |
FAILED_CREATE_OPERATION / FAILED_ENQUEUE_OPERATION | DB or Redis hiccup; try again, then escalate |
Webhooks (incoming)
| Code | Means |
|---|---|
INVALID_SIGNATURE | Inbound webhook HMAC mismatch (Provisioner → DT Edge Platform); secret out of sync |
STALE_TIMESTAMP | Replay window exceeded (>5 min) |
WEBHOOK_NOT_FOUND | The webhook config row was deleted |
Generic
| Code | Means |
|---|---|
INTERNAL_SERVER_ERROR | Unhandled exception; check pod logs |
DB_UNAVAILABLE | Postgres is down or unreachable |
RATE_LIMITED | Per-API-key rate limit hit; back off |
See also
- How-to: handle fleet quota exceeded
- How-to: upload license
- Backend docs: API → Error codes