Directus API Bug: Bulk Policy Updates Failing

Aug 15, 2025 by Henrik Larsen 46 views

Directus Bulk API Policy Update Bug: Only One Policy Accepted

Hey guys! It looks like there's a bit of a snag when trying to update policies in bulk using the Directus API. Let's dive into the details and see what's going on.

The Issue: Bulk API for Policies Expects Single Policy

So, the main problem is that when you try to use the Directus API to update multiple policies at once, it throws an error. According to the API documentation, the data field should accept an array of policies. However, the debug logs from self-hosted Directus instances are showing that it's actually expecting a single object instead of an array. This discrepancy is causing headaches for developers who are trying to manage policies efficiently.

When working with Directus and its API, one expects the bulk operations to function as documented, allowing for efficient management of multiple entities. However, this issue reveals a mismatch between the documented behavior and the actual implementation. The API documentation suggests that the data field in the request body for bulk policy updates should accept an array of policy objects. This would align with the standard practice of bulk operations, where multiple entities can be created, updated, or deleted in a single request. However, the debug logs indicate that the system is expecting a single policy object instead of an array. This expectation leads to an error when an array is provided, disrupting the intended bulk operation. This behavior is not only counterintuitive but also creates friction in managing policies, as developers must resort to sending individual requests for each policy update. Such a workaround significantly reduces efficiency and increases the complexity of managing policies, especially in environments with numerous policies. The error message, "data" must be of type object., clearly points to this mismatch, making it evident that the API is not processing the request as a bulk operation. Understanding this discrepancy is crucial for developers to adjust their approach and for the Directus team to address this bug in future releases. This kind of issue underscores the importance of aligning documentation with actual code behavior and thoroughly testing bulk operations to ensure they function as expected.

Debug Logs Showing the Error

Here's a snippet from the logs that highlights the issue:

[09:19:08.813] DEBUG: Invalid payload. "data" must be of type object.

    err: {

      "type": "",

      "message": "Invalid payload. \"data\" must be of type object.",

      "stack":

          DirectusError: Invalid payload. \"data\" must be of type object.

              at file:///directus/node_modules/.pnpm/@directus+api@file+api_@[email protected][email protected]/node_modules/@directus/api/dist/middleware/validate-batch.js:40:15

              at file:///directus/node_modules/.pnpm/@directus+api@file+api_@[email protected][email protected]/node_modules/@directus/api/dist/utils/async-handler.js:1:66

              at Layer.handle [as handle_request] (/directus/node_modules/.pnpm/[email protected]/node_modules/express/lib/router/layer.js:95:5)

              at next (/directus/node_modules/.pnpm/[email protected]/node_modules/express/lib/router/route.js:149:13)

              at Route.dispatch (/directus/node_modules/.pnpm/[email protected]/node_modules/express/lib/router/route.js:119:3)

              at Layer.handle [as handle_request] (/directus/node_modules/.pnpm/[email protected]/node_modules/express/lib/router/layer.js:95:5)

              at /directus/node_modules/.pnpm/[email protected]/node_modules/express/lib/router/index.js:284:15

              at Function.process_params (/directus/node_modules/.pnpm/[email protected]/node_modules/express/lib/router/index.js:346:12)

              at next (/directus/node_modules/.pnpm/[email protected]/node_modules/express/lib/router/index.js:280:10)

              at file:///directus/node_modules/.pnpm/@directus+api@file+api_@[email protected][email protected]/node_modules/@directus/api/dist/middleware/use-collection.js:4:5

      "name": "DirectusError",

      "extensions": {

        "reason": "\"data\" must be of type object"

      },

      "code": "INVALID_PAYLOAD",

      "status": 400

    }

[09:19:08] PATCH /policies 400 6ms

This log clearly shows that the system is expecting the data field to be an object, which contradicts the documentation stating it should be an array for bulk operations. This invalid payload error is a crucial indicator of the bug, making it difficult for users to update policies efficiently. The error message specifically points out that the data field must be of type object, which means that the Directus API is interpreting the request as an attempt to update a single policy rather than multiple policies in bulk. This is further evidenced by the stack trace, which leads back to the validation middleware within the Directus API. The middleware is responsible for ensuring that the incoming request payload conforms to the expected structure. In this case, it appears that the validation logic is not correctly handling the array format for the data field, leading to the INVALID_PAYLOAD error. Understanding this error message and its context is essential for troubleshooting and resolving the issue. It highlights the need for consistent handling of data types within the API and accurate alignment with the documentation. For developers, recognizing this error quickly can save significant time and effort in debugging their applications. It also emphasizes the importance of referring to debug logs when encountering unexpected behavior in an application, as they often provide valuable insights into the root cause of the problem.

How to Reproduce the Bug

If you want to see this in action for yourself, you can use a curl command like this:

curl -f -vv -X PATCH "$TARGET_URL/policies" \
  -H "Authorization: Bearer $TARGET_TOKEN" \
  -H "Content-Type: application/json" \
  -d "@init/policies.json"

Make sure you replace $TARGET_URL and $TARGET_TOKEN with your actual Directus URL and token. The @init/policies.json file should contain an array of policy objects. Running this command will likely result in the same error we saw in the logs.

To reproduce this bug in Directus, you need to send a PATCH request to the /policies endpoint with a JSON payload that contains an array of policy objects. This is because the intention is to update multiple policies in bulk. However, the Directus API, due to the bug, expects the data field to contain only a single policy object. The -f flag in the curl command ensures that the command fails silently on server errors. The -vv flag provides verbose output, which is useful for debugging as it displays detailed information about the request and response. The -X PATCH option specifies that the request method is PATCH, which is typically used for updating resources. The -H flags set the headers for the request, including the Authorization header with the bearer token for authentication and the Content-Type header to indicate that the request body is in JSON format. The -d option specifies the data to be sent in the request body, in this case, the contents of the policies.json file. This file should contain an array of policy objects, each representing a policy to be updated. When this command is executed, Directus will process the request and, due to the bug, return a 400 status code with an error message indicating that the payload is invalid because it expects a single object instead of an array. This reproduction step is crucial for verifying the bug and ensuring that it is properly addressed in future updates. By following these steps, developers and testers can confirm the issue and contribute to its resolution, ultimately improving the stability and functionality of Directus.

Directus Version and Hosting

This bug was observed on Directus version 11.10.2, and it's happening on self-hosted instances using a Docker image. So, if you're running a similar setup, you might encounter this issue.

It's important to note the specific version of Directus where this bug is observed because software systems often undergo changes and fixes in each release. Knowing that the bug occurs in version 11.10.2 helps developers and users narrow down the scope of the issue and determine whether they are affected. This version information is crucial for those who manage Directus instances, as they can use it to decide whether to apply a patch or upgrade to a later version that addresses the bug. The fact that the bug is observed on self-hosted instances using a Docker image further contextualizes the issue. Self-hosted deployments often have unique configurations and environments, which can sometimes introduce or exacerbate bugs. Docker images provide a consistent environment, but the interaction between Directus and the Docker setup may still play a role in the bug's manifestation. This information is valuable for the Directus team as they investigate the bug, as it may point to specific interactions between the Docker environment and the API's behavior. Understanding the hosting strategy and the deployment environment can lead to more targeted debugging and ultimately a more effective solution. It also helps users in similar environments share their experiences and potentially discover workarounds or temporary fixes while waiting for an official patch.

Database

The database being used is Postgres. This information might be relevant as the way Directus interacts with the database could potentially play a role in the bug. While the bug appears to be related to the API's input validation, knowing the database type can help in a thorough investigation.

Specifying the database being used, which in this case is Postgres, is essential for a comprehensive understanding of the bug's context. While the primary issue seems to be related to the API's input validation logic, the underlying database and its interaction with Directus can sometimes influence how such bugs manifest. Postgres is a robust and widely used relational database, but specific configurations, extensions, or data types within the database could potentially interact with the API in unexpected ways. For instance, certain data types or constraints might trigger different code paths within Directus, leading to the observed behavior. Additionally, the database version and any custom database settings could also play a role. By including this information, developers and investigators can consider whether there are any database-specific aspects that might be contributing to the issue. This is particularly important if the bug seems intermittent or if it only occurs under certain conditions. Furthermore, knowing that Postgres is being used allows for more targeted testing and debugging strategies. For example, the Directus team might focus on examining the queries generated by the API and how they interact with the Postgres database to identify any potential discrepancies or inefficiencies. Therefore, the database information is a valuable piece of the puzzle when diagnosing and resolving this bug.

Conclusion

So, there you have it! It seems like the Bulk API ops for policies in Directus 11.10.2 are expecting a single policy object instead of an array, which is a bug. If you're facing this issue, you're not alone. Hopefully, this will be addressed in a future release. Keep an eye on Directus updates, and in the meantime, you might need to update your policies one by one. Happy coding, guys! Let's hope for a fix soon so we can get back to smooth bulk updates.