Troubleshooting guide for Directus FORBIDDEN errors

directus_debug_guide.md

Directus debug guide

Directus is a highly flexible and well architectured CMS, that is by design nearly impossible to debug. You will encounter the following error message for 391 different reasons

[FORBIDDEN] You don't have permission to access this

In other cases you'll just face an Unknown error to further help you on the way. I mean, at least that's not outright misleading.

In this document I'm collecting some of these errors

1. FORBIDDEN errors during production deployment

Most common causes:

• Filesystem permission errors
• Not having copied over all files
• Folder ownership not carried over by git.

Important to note: host filesystem permissions (even 777) worth nothing. You need to go into the container and execute a chown like this:

docker-compose exec -u root <container> chown -R node:node /directus/database /directus/extensions /directus/uploads

If the problem persists, check docker logs

2. Unable to login / Unknown error during production deployment

Most common causes:

• The database file has incorrect container level filesystem permissions.
• The database file is corrupted.

3. FORBIDDEN errors after creating a new collection

Most common cause:

• Incorrect permission settings under Settings (cogwheel icon) > Access Control > Public

4. FORBIDDEN errors in API calls

Most common causes:

• Table name is incorrect in the query
• Field name(s) are incorrect in the query
• API call is not authorized with the correct user
• GraphQL query is semantically incorrect

5. FORBIDDEN errors during file / image upload

• Filesystem permission errors
• Max upload filesize limitation exceeded (check nginx, apache configs)
• Expired access token
• Incorrect access token
• User IP address is not allowed in Directus config (if whitelisting is enabled)

6. API endpoints are not reachable from FE application

This is not a Directus issue, but so common that it's worth mentioning. It's only possible to deploy some JS FE applications in the same docker environment if you configure depends_on in docker-compose.yml and/or write a custom startup script that first waits for the BE to spin up.

docker-compose (relevant part):

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8055/admin/login"]
      interval: 5s
      timeout: 2s
      retries: 10

startup script example:

#!/bin/bash

# Start the backend in detached mode
echo "Starting backend service..."
docker-compose up -d backend

# Wait for the backend to be healthy
echo "Waiting for backend to become healthy..."
while ! docker inspect -f '{{.State.Health.Status}}' backend-api | grep -q "healthy"; do
  sleep 5
  echo "Still waiting for backend to become healthy..."
done
echo "Backend is healthy!"

# Now build and start the frontend
echo "Building and starting frontend service..."
docker-compose up --build frontend

During prod deploy, in most modern FE applications, the possibly changed directus API domain/IP also needs to be configured to avoid CORS issues that would result in a build fail or runtime issue.

In all other cases, basic network debugging will likely help. Fire requests from an empty container, check DNS resolution, docker networks, host file, reverse proxy settings, etc.