Troubleshooting
Common errors, diagnostics, and fixes for Directus MCP and API.
Quick Diagnostics
Check MCP Connection
Call the schema tool with no parameters. If it returns collections, MCP is connected.
Tool: schema
Input: {}
If this fails, the MCP server is not reachable or the token is invalid.
Check API Health
# Liveness: public, answers once the HTTP server runs (no database check)
curl "${DIRECTUS_URL}/server/ping"
# Should return: "pong"
# Dependency health (database, Redis, storage, email).
# Directus 12 answers 403 FORBIDDEN without a token.
curl "${DIRECTUS_URL}/server/health" \
-H "Authorization: Bearer ${DIRECTUS_TOKEN}"
# Test token validity
curl "${DIRECTUS_URL}/users/me" \
-H "Authorization: Bearer ${DIRECTUS_TOKEN}"
MCP-Specific Errors
"action is required"
Cause: Missing action parameter in MCP tool call.
Fix: Always include "action": "read" (or create/update/delete):
{ "action": "read", "collection": "posts", "query": { "limit": 10 } }
"collection is required"
Cause: items, fields tools need a collection name.
Fix: Add "collection": "your_collection_name".
"data must be an array"
Cause: Items create expects data as an array.
Fix: Wrap single items in an array:
{ "action": "create", "collection": "posts", "data": [{ "title": "Test" }] }
Empty response from schema
Cause: User has no read permissions on collections.
Fix: Check that a policy attached to the MCP user (directly or through the user's role) grants read access to directus_collections, directus_fields, directus_relations.
Tool not found
Cause: MCP server ID doesn't match tool prefix.
Fix: List available tools. If your MCP server is registered as directus-1, tools are mcp__directus-1__*, not mcp__directus__*.
Only search, execute and schema are listed
Cause: The MCP URL ends in ?tool_mode=registry. Registry mode exposes three root tools instead of the individual ones.
Fix: Either work through them (search finds a tool and loads its input details, execute runs it with the tool name and input, schema reads the data model directly) or connect to plain /mcp if your client has its own tool search. See the mcp-tools skill.
/mcp does not respond (403 MCP must be enabled)
Cause: MCP is disabled by default (the server answers 403 FORBIDDEN, "MCP must be enabled"), or Directus is below v11.12, or (Directus 12) the instance is over its license limits and the grace period has ended. In that locked-down state GraphQL, WebSockets and MCP are disabled and /items calls fail.
Fix:
- Enable it in Settings → AI → Model Context Protocol (an administrator can block that toggle with
MCP_ENABLED=false) - Check the version with
GET /server/info(a token is needed for details) - For a license lock-down, an admin signs in to the Data Studio, where the resolution flow asks for a license or for usage to come back inside the Core tier limits. No data is deleted by enforcement.
OAuth sign-in loops or is refused
Cause: The OAuth server is off or the client registration method is not enabled.
Fix: Set MCP_OAUTH_ENABLED=true, enable MCP_OAUTH_CIMD_ENABLED (preferred) or MCP_OAUTH_DCR_ENABLED for clients that need Dynamic Client Registration, set PUBLIC_URL to the externally visible URL, restart, then switch the same options on in Settings → AI → Model Context Protocol. If the client cannot do OAuth, use a static token.
HTTP Status Errors
401 Unauthorized
Cause: Missing, expired, or invalid token.
Fix:
- Check token is included in header:
Authorization: Bearer TOKEN - For JWTs: token may have expired (default 900s) — refresh it
- For static tokens: verify in User Directory > user profile > Token field
403 Forbidden
Cause: User has valid token but insufficient permissions.
Fix:
- Permissions live in policies (Directus 11+). Open Settings → Access Policies → [policy] → Permissions, for every policy that reaches the user. The user's effective permissions are the aggregate of the policies attached directly to the user, to the user's role and to that role's parent roles
- A policy with an IP allowlist is dropped entirely when the request comes from another IP
- Common missing permissions:
- Read on system collections (
directus_collections,directus_fields) - Create/Update on target collections
- Schema management permissions for collection/field creation
- Read on system collections (
- For MCP: ensure the MCP user has permissions matching intended operations
- Since 12.4.0, update/delete by
queryalso needs read on the collection's primary key - Error
COLLECTION_INACTIVE(403): the collection's status is Inactive, usually because the instance went over its license collection limit. Set it back to Active in the collection settings, or add a license
403 on file assets (/assets/{id}) — the most common 403 issue when integrating with frontends:
- Directus file assets require authentication by default — unauthenticated requests to
/assets/{id}return 403 - Fix option 1 (everything is public): Grant the Public policy read access to
directus_files(Settings → Access Policies → Public →directus_files→ enable Read). Everything unauthenticated requests can reach is controlled by that one policy, so keep it minimal. Without a license this must be an unrestricted rule: a folder filter or a field list is a custom permission rule, and creating it answers403 RESOURCE_RESTRICTED(custom_permission_rules_enabled; seen on Directus 12.4.1). The consequence is that every file of the instance becomes downloadable, and listable throughGET /files, by anyone. Do not use this on an instance that also stores private uploads - Fix option 2 (private or mixed files): Serve assets through a server route of your own that adds the token server-side, and restrict it to the files you mean to publish (for example by folder, checked in the route)
- Do not put
?access_token=into a URL that reaches a browser (<img src>, HTML, ornext/image, whose/_next/image?url=carries the whole source URL into the page): the token is then readable by every visitor and lands in access logs. A static token in a URL is for server-to-server calls only - When using
next/image, the 403 manifests as broken/missing images with no obvious error since Next.js proxies through/_next/image
403 on /server/health — Directus 12 requires a token for it. Use /server/ping for liveness probes and send a token only when you need dependency status.
404 Not Found
Cause: Collection, item, or endpoint doesn't exist.
Fix:
- Verify collection name with
schematool (discovery mode) - Check item UUID exists before updating/deleting
- Confirm API endpoint path is correct
409 Conflict
Cause: Unique constraint violation or concurrent modification.
Fix:
- Check for duplicate values on unique fields
- Re-read the item before retrying update
- For collections: check if name already exists
422 Unprocessable Entity
Cause: Validation error — required field missing, wrong data type, or constraint violation.
Fix:
- Read the schema to understand required fields:
schematool withkeys: ["collection"] - Check field types match expected values
- Common issues:
- String field receiving a number
- Non-nullable field missing in create
- UUID field receiving invalid format
- Relation field referencing non-existent target
429 Too Many Requests
Cause: Rate limiting.
Fix: Wait and retry with exponential backoff. Reduce batch sizes.
413 Content Too Large
Cause: An import or a schema snapshot (/schema/diff, /schema/apply, /utils/import/{collection}) is larger than IMPORT_MAX_FILE_SIZE, which defaults to 50mb since Directus 12.2.0.
Fix: Split the file, or raise IMPORT_MAX_FILE_SIZE.
500 Internal Server Error
Cause: Server-side error.
Fix:
- Check Directus server logs
- May indicate database connection issues
- May indicate extension errors
- On Directus 12.4.0, reading
directus_foldersas a non-admin fails with 500 (breaks the File Library andGET /folders). Upgrade to 12.4.1 or later
Directus 12 Notes
| Symptom | Cause | Fix |
|---|---|---|
| SSO users cannot log in, custom permission rules ignored, custom LLM connections fail | Directus 12 enforces licensing. SSO, custom permission rules and custom or self-hosted LLMs need a licensed tier. Upgraded instances get a 30 day grace period | Add a license, or return to Core tier features. Admin sees a reminder at login during the grace period |
GraphQL, WebSockets and MCP stopped, /items calls fail, non-admins cannot log in |
Grace period ended and the instance is over its limits | Resolve through the Data Studio resolution flow (license or reduced usage). No data is deleted |
LIMIT_EXCEEDED ("flows limit exceeded", and similar for other resources) when creating something |
The Core tier has entitlement limits (user seats, collections, flows and more, see the Directus pricing page). A fresh unlicensed instance hits the flows limit quickly | Delete unused resources or add a license |
403 COLLECTION_INACTIVE on REST, GraphQL, WebSockets, MCP or a flow operation |
Collection status is Inactive (12.4.0+) | Set the collection back to Active, or add a license |
403 from /server/health |
Token now required | Use /server/ping, or send a token |
413 on import or schema diff |
IMPORT_MAX_FILE_SIZE default 50mb (12.2.0+) |
Raise the limit |
ILLEGAL_ASSET_TRANSFORMATION |
Output above ASSETS_TRANSFORM_IMAGE_MAX_OUTPUT_DIMENSION (default 6000, 12.3.0+) at any step of the transformation |
Lower the requested size or raise the variable |
| Client IPs show the proxy address, IP allowlists misbehave behind a reverse proxy | IP_TRUST_PROXY now defaults to false |
Set IP_TRUST_PROXY=true (or a narrower trust setting) when you run behind a proxy |
| WebSocket connections rejected | CORS_ORIGIN is enforced for WebSockets (12.1.0+) |
Add the client origin to CORS_ORIGIN |
Flow Update or Delete Items operation does nothing and returns null |
Empty or missing key and query no longer target every item (12.3.0+) |
Set a key, or an explicit query such as {"limit": -1}. See flow-automation |
npm/npx missing inside the container |
Hardened image (12.1.0+) | Build extensions outside the container, see the Docker local dev skill |
Schema Errors
"Collection already exists"
Fix: Use schema tool to check existing collections before creating.
"Field already exists"
Fix: Read fields first: fields tool with action: "read" and collection name.
"Related collection does not exist"
Cause: Creating a relation to a collection that hasn't been created yet.
Fix: Create collections in dependency order. Independent collections first, then dependent ones.
"Invalid foreign key"
Cause: Relation target doesn't exist or field type doesn't match.
Fix:
- Ensure both collections exist
- Ensure the M2O field is
uuidtype (matching the target's primary key type) - Ensure the relation field has been created before creating the relation
Flow Errors
Operations not executing
Cause: Operations not connected via resolve/reject.
Fix:
- Read the flow:
flowstool withaction: "read"and flow key - Verify
operationfield on the flow points to the first operation - Verify each operation's
resolve/rejectpoints to the next operation
Condition not matching
Cause: Wrong filter syntax in condition operation.
Fix: Use nested objects, NOT dot notation:
// CORRECT
{ "$trigger": { "payload": { "status": { "_eq": "published" } } } }
// WRONG — will never match
{ "$trigger.payload.status": { "_eq": "published" } }
Request operation failing
Cause: Wrong header or body format.
Fix:
- Headers must be array:
[{ "header": "Content-Type", "value": "application/json" }] - Body must be stringified JSON:
"{\"key\": \"value\"}"
Data chain variable empty
Cause: Referencing wrong operation key.
Fix: Use the exact key value set on the operation. Don't use $last.
Performance Issues
Slow Queries
- Add
fieldsparameter — don't fetch all fields - Use
limit— don't fetch all records - Simplify
deepqueries — nested relation queries are expensive - Filter at API level, not in code
Large Batch Operations
- Process in batches of 10-25 items
- Add delays between batches if hitting rate limits
- Use
offsetpagination instead of fetching everything
MCP Response Timeout
- Reduce query complexity (fewer nested relations)
- Add
limitto all queries - Split large operations into smaller sequential calls
Permission Debugging
Check What a User Can Do
Permissions belong to policies. Start from what the current token can do:
curl "${DIRECTUS_URL}/permissions/me" \
-H "Authorization: Bearer ${DIRECTUS_TOKEN}" | jq .data
It lists every collection with an access level per action (none, partial, full).
Find Which Policies Reach a User
curl "${DIRECTUS_URL}/users/<user-uuid>?fields=email,policies.policy.name,role.name,role.policies.policy.name,role.parent.policies.policy.name" \
-H "Authorization: Bearer ${DIRECTUS_TOKEN}" | jq .data
Check What a Policy Grants
curl "${DIRECTUS_URL}/permissions?filter[policy][_eq]=<policy-uuid>&limit=-1" \
-H "Authorization: Bearer ${DIRECTUS_TOKEN}" | jq '.data[] | {collection, action}'
Common Permission Setup for MCP User
Minimum permissions for a developer MCP user:
| Collection | Actions |
|---|---|
| All user collections | Create, Read, Update, Delete |
directus_collections |
Create, Read, Update, Delete |
directus_fields |
Create, Read, Update, Delete |
directus_relations |
Create, Read, Update, Delete |
directus_files |
Create, Read, Update, Delete |
directus_folders |
Create, Read, Update, Delete |
directus_flows |
Create, Read, Update, Delete |
directus_operations |
Create, Read, Update, Delete |
directus_users |
Read |
directus_roles |
Read |
Enable "Allow Deletes" in MCP settings if deletion via MCP is needed.