[Bug]: Custom Controller Sanitization Documentation referencing V4 way

[tomh4]

Link to the documentation page or resource

https://docs.strapi.io/cms/backend-customization/controllers#sanitization-and-validation-in-controllers

Describe the bug

In the documentation it still says to use the old way of sanitizing content in custom controllers, even though this is no longer working.

import { sanitize, validate } from '@strapi/utils';

export default {
  async findCustom(ctx) {
    const contentType = strapi.contentType('api::test.test');

    await validate.contentAPI.query(ctx.query, contentType, { auth: ctx.state.auth });
    const sanitizedQueryParams = await sanitize.contentAPI.query(ctx.query, contentType, { auth: ctx.state.auth });

    const documents = await strapi.documents(contentType.uid).findMany(sanitizedQueryParams);

    return await sanitize.contentAPI.output(documents, contentType, { auth: ctx.state.auth });
  }
}

Additional context

In the migration docs it is outline to use the new way:
https://docs.strapi.io/cms/migration/v4-to-v5/breaking-changes/strapi-utils-refactored#additional-notes

// Strapi v4
import { validate, sanitize } from '@strapi/utils';

validate.contentAPI.xxx();
sanitize.contentAPI.xxx();

// Strapi 5
// Those methods require the strapi app context
strapi.contentAPI.sanitize.xxx();
strapi.contentAPI.validate.xxx();

Suggested improvements or fixes

Add the new way to the docs so they are correct again

Related issue(s)/PR(s)

No response

[github-actions]

🤖 I've analyzed your question and here's what I found:

Thank you so much for taking the time to report this and for providing such a clear example and suggested improvement—your attention to detail really helps us make Strapi better for everyone! 🙏

You're absolutely right: with Strapi 5, the approach to sanitization and validation in custom controllers has changed. The methods from @strapi/utils (sanitize.contentAPI.xxx and validate.contentAPI.xxx) now require the Strapi app context and should be accessed via strapi.contentAPI.sanitize.xxx() and strapi.contentAPI.validate.xxx() instead of direct imports. This is outlined in the migration notes, but the main documentation page you referenced still shows the v4 approach, which can definitely cause confusion for developers upgrading or starting fresh with v5.

Correct usage in Strapi 5:

// Strapi 5 way
export default {
  async findCustom(ctx) {
    const contentType = strapi.contentType('api::test.test');

    await strapi.contentAPI.validate.query(ctx.query, contentType, { auth: ctx.state.auth });
    const sanitizedQueryParams = await strapi.contentAPI.sanitize.query(ctx.query, contentType, { auth: ctx.state.auth });

    const documents = await strapi.documents(contentType.uid).findMany(sanitizedQueryParams);

    return await strapi.contentAPI.sanitize.output(documents, contentType, { auth: ctx.state.auth });
  }
}

This change is also described in the Strapi v4 to v5 migration breaking changes documentation.

Next steps:

• We'll flag this for the documentation team to update the Sanitization and Validation in controllers page to reflect the new Strapi 5 approach.
• In the meantime, please use the strapi.contentAPI.sanitize and strapi.contentAPI.validate methods as shown above for your custom controllers.

If you have any more questions or run into other migration issues, feel free to reach out here or join our Discord community for real-time support.

Thanks again for helping us improve Strapi! If you have further suggestions, you can also submit them at feedback.strapi.io.

If this is blocking your work or you believe it's a product bug rather than just a documentation issue, please let us know and we can escalate it to the core team (@pwizla).

Have a great day and happy coding! 🚀

📚 Relevant documentation:

• strapi-utils refactored - Additional Notes
• Controllers - Adding a new controller
• Controllers - Extending core controllers
• Controllers - Sanitization and Validation in controllers
• Controllers - Sanitization and validation when building custom controllers
• Core service methods use the Document Service API
• Entity Service API to Document Service API migration reference - Manual migration
• Examples cookbook: Custom services and controllers - Custom controller
• Release notes - 5.1.1
• Release notes - New content
• Release notes - Updated content
• REST API input is validated by default in controllers
• Step-by-step guide to upgrade to Strapi 5 - Step 4: Migrate the API consuming side
• Strapi v4 to Strapi 5 breaking changes - Content API
• Upgrading to Strapi 5: Introduction and FAQ

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.

[pwizla]

Thanks for reporting! Fixed in #2661 (merged & live on docs.strapi.io in a few moments)

[tomh4]

Thanks for the quick fix!