Strapi v5 Plugin API: Breaking Changes#

Overview#

Strapi v5 removed the @strapi/helper-plugin package entirely and replaced it with exports spread across @strapi/strapi/admin and @strapi/design-system. Any plugin or custom admin code that still imports from @strapi/helper-plugin will crash the admin panel at runtime. The most visible symptom is TypeError: checkUserHasPermissions is not a function, caused by the useRBAC hook trying to call a function that no longer exists in the expected location. 1

Key breaking changes affecting plugin developers:

• @strapi/helper-plugin removed — all ~50 exports relocated or deleted. (breaking change doc)
• useRBAC hook signature changed — argument format changed from an object to an array. (RBAC breaking change doc)
• content-manager_rbacManager redux store section removed — the regular permissions system replaces it. 2
• useRBACProvider removed — replaced by the useAuth hook. 3

useRBAC: Signature Change#

The useRBAC hook is now imported from @strapi/strapi/admin (not @strapi/helper-plugin) and its first argument changed from a named-key object to a flat array of permissions. 2

Passing an object still works in v5 but logs a deprecation warning: "useRBAC: The first argument should be an array of permissions, not an object. This will be deprecated in the future." 4

The hook signature in v5: useRBAC(permissionsToCheck, passedPermissions?, rawQueryContext?). Action names are derived from the last dot-separated segment, with hyphens removed and CamelCased — e.g. admin::roles.create-draft → canCreateDraft. 5

Internally, useRBAC retrieves checkUserHasPermissions via useAuth selector 6 and calls it inside a useEffect 7. If the Auth context is not initialized — for example, because an old plugin is rendering outside the v5 provider tree — checkUserHasPermissions is undefined and the crash occurs.

checkUserHasPermissions and the Auth Context#

In v5, checkUserHasPermissions lives in the Auth context, defined in packages/core/admin/admin/src/features/Auth.tsx. It is a useCallback that:

1. Short-circuits if permissions is empty. 8
2. Filters the current user's permissions against the requested ones by action and optionally subject. 9
3. Runs them through the RBAC middleware (supports custom rawQueryContext). 10
4. If conditions are present, validates against the backend API; otherwise returns immediately. 11

To access checkUserHasPermissions directly (replacing the removed hasPermissions util from helper-plugin): 12

import { useAuth } from '@strapi/strapi/admin';

const { checkUserHasPermissions } = useAuth(
  'COMPONENT_NAME',
  (state) => state.checkUserHasPermissions
);

Migration Map: Key helper-plugin Exports#

Full reference: Helper-plugin migration guide 13

The v5 upgrade tool includes a deprecate-helper-plugin codemod that handles a subset of these changes automatically 15, but many require manual migration.

Diagnosing and Fixing the Crash#

Symptom: Admin panel crashes with TypeError: checkUserHasPermissions is not a function or Cannot read properties of undefined (reading 'tours').

Root cause: A plugin (custom or third-party) still imports from @strapi/helper-plugin or uses the v4 useRBAC object-argument syntax. 1

Diagnosis steps:

1. Search installed plugins for deprecated imports:

   ⧉

   grep -r "helper-plugin" ./node_modules --include="package.json" -l
   grep -r "from '@strapi/helper-plugin'" ./src -l
   

2. Check third-party plugins for v5 compatibility notes in their changelogs.

3. If no plugins are found, the error may be a version-specific bug — it was reproduced in v5.31.3 and resolved in v5.34.0. 1

Fix:

• Migrate all imports per the helper-plugin migration reference.
• Update useRBAC calls from object-argument to array-argument format. 2
• Replace useRBACProvider with useAuth. 3
• Run codemods via npx @strapi/upgrade@latest 5.0.0 then audit remaining manual changes.
• After updating, clean and rebuild:
  ⧉

  rm -rf .cache build dist node_modules && npm install && npm run build
  

Key source files:

• useRBAC hook — packages/core/admin/admin/src/hooks/useRBAC.ts
• Auth.tsx (checkUserHasPermissions) — packages/core/admin/admin/src/features/Auth.tsx
• deprecate-helper-plugin codemod