Skip to content

Error Codes admin

github-actions[bot] edited this page Nov 16, 2026 · 1 revision

Error codes: @ultimat3/admin

Part of Error codes: every code @ultimat3/admin registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
X_ADMIN_ACTION_DUPLICATE two registered admin actions carry one name the same action name declared on two entities, or on an entity and the global toolbar. Refused at defineAdmin, not at the first call: the name is the MCP tool name, the default label key and the key callAdminTool resolves a handler by, so a collision is a call that succeeds against the wrong action and reports nothing rename one in defineAdmin's actions — name: '<entity>.<action>' — so the bare name belongs to one of them; the cause names both holders
X_ADMIN_ACTION_NOT_APPLICABLE an admin action was run on a row its when() rule excludes the row changed state after the button rendered, or the call was forged for a row the action does not apply to x manifest --json — admin[].resources[].actions marks the action when: true; re-read the row (the detail page, or the admin.<entity>.read tool) and run the action only while its when() holds
X_ADMIN_DENIED the actor may not use this admin surface missing admin:* permission grant the permission through the normal policy layer
X_ADMIN_ENTITY_UNKNOWN the admin references an entity that does not exist a renamed entity x g entity <name>, then x manifest
X_ADMIN_FIELD_UNSUPPORTED a column type the admin cannot render an exotic Postgres type supply a custom field renderer, or hide the column
X_ADMIN_FILTER_INVALID an admin list was asked for a filter, sort or scope its resource does not derive the list URL carried a parameter other than cursor, sort, scope or f.*; a sort on a field that is not sortable or a direction other than asc/desc; a scope the resource does not declare; or an f.<field>.<op> the field's shape does not offer — a sealed column offers none. Refused (400), never ignored: an ignored filter is a list that answers rows the reader thinks were excluded x manifest --json — admin[].resources lists the filters, sorts and scopes of the entity the cause names
X_ADMIN_INVALID an admin tool's arguments failed the resource schema the agent built a row from a stale tool schema x manifest, then re-read the tool's JSON Schema from tools/list
X_ADMIN_MOUNT_MISSING an admin batch job ran in a process that never declared its admin a batch above its threshold was queued by the web role, and the worker that claimed the chunk imported no module calling defineAdmin() import the module that calls defineAdmin() from apps/web/api/index.ts, so the worker role loads it; then x verify --only manifest
X_ADMIN_PAGE_PATH_INVALID a custom admin page has an unusable or already-taken path a path that is not rooted, or one that shadows a generated resource route — the generated screen would become unreachable give the page a rooted path that no resource already claims, e.g. '/ops'; the cause names the collision
X_ADMIN_PAGE_UNGUARDED a custom admin page declared no permissions a pages: entry with an empty permissions array. Refused at declaration rather than at a request, because the author never writes the defineRoute call — adminRouteConfig emits it with the policy composed in, so a page cannot reach the router unguarded add permissions: ['<subject>:read'] to the pages entry for '<path>'; the frame's admin:read is prepended for you
X_ADMIN_POLICY_MISSING an admin-exposed subject has no policy a screen added without authz add policy: can('<subject>') to the definition
X_ADMIN_READ_ONLY_WRITE an admin resource over a readOnly entity offers a write the resource's operations name create, edit or delete on an entity declared entity({ readOnly: '' }), whose every write is refused drop the writes from its admin resource's operations, or name only list, detail, search
X_ADMIN_REPO_UNBOUND an admin resource has no database handle to read rows through defineAdmin() was given an entity and neither a db handle that carries it nor a per-resource repo. Refused at declaration: a resource with no repo is a list, a detail and a form that all fail on their first request pass the app's handle once: defineAdmin({ entities, db }) — or resources: { : { repo } } for one resource
X_ADMIN_TOOL_FORBIDDEN an admin MCP tool was called without permission agent acting beyond its user nothing to fix — the policy is correct
X_ADMIN_VIEW_WRITE an admin resource over a view entity offers a write adminResource or defineAdmin's resources.<entity>.operations names create, update or delete for an entity declared with view: { sql }, whose rows Postgres derives and no write can land on x entities show <entity> --json # then drop operations from its admin resource (a view lists read-only), or name only list, detail, search
X_DEV_DASHBOARD_IN_PROD /_x was mounted outside dev the dev dashboard shipped in the image delete the /_x mount from the production entrypoint

Clone this wiki locally