{"record":{"id":"06e761f4da8247fb","repo":"strapi/strapi","slug":"middleware-uid-has-already-been-registered","errorCode":null,"errorMessage":"Middleware ${uid} has already been registered.","messagePattern":"Middleware (.+?) has already been registered\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/core/src/registries/middlewares.ts","lineNumber":50,"sourceCode":"\n    /**\n     * Registers a middleware\n     */\n    set(uid: UID.Middleware, middleware: Core.Middleware) {\n      middlewares[uid] = middleware;\n      return this;\n    },\n\n    /**\n     * Registers a map of middlewares for a specific namespace\n     */\n    add(namespace: string, rawMiddlewares: Record<string, Core.Middleware> = {}) {\n      for (const middlewareName of Object.keys(rawMiddlewares)) {\n        const middleware = rawMiddlewares[middlewareName];\n        const uid = addNamespace(middlewareName, namespace) as UID.Middleware;\n\n        if (has(uid, middlewares)) {\n          throw new Error(`Middleware ${uid} has already been registered.`);\n        }\n        middlewares[uid] = middleware;\n      }\n    },\n\n    /**\n     * Wraps a middleware to extend it\n     */\n    extend(uid: UID.Middleware, extendFn: MiddlewareExtendFn) {\n      const currentMiddleware = this.get(uid);\n\n      if (!currentMiddleware) {\n        throw new Error(`Middleware ${uid} doesn't exist`);\n      }\n\n      const newMiddleware = extendFn(currentMiddleware);\n      middlewares[uid] = newMiddleware;\n","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/strapi/strapi/blob/4a4101264d7098754df36e85fa629fd2f2349d8c/packages/core/core/src/registries/middlewares.ts#L32-L68","documentation":"Thrown by `strapi.middleware.add(namespace, middlewares)` when a middleware name, once namespaced (via `addNamespace`), collides with an already-registered UID. Middlewares are stored in a map keyed by UID and the registry refuses to overwrite. The error fires during the per-key loop, so the first middleware in the batch that collides aborts the whole add.","triggerScenarios":"Two plugins defining a middleware with the same name. A plugin re-declaring a middleware Strapi core already registered (e.g. `global::cors`, `plugin::users-permissions.jwt`). Hot-reload during `develop` re-running `add()` against a non-cleared registry.","commonSituations":"Plugin named `users-permissions` re-registering `jwt`. Local plugin loaded twice (npm package + local path). Hot-reload double-registration. Forking a plugin and forgetting to rename the middleware file.","solutions":["Rename the conflicting middleware in `server/src/middlewares/<name>.ts` so its namespaced UID is unique.","Restart the dev server cleanly if you suspect HMR double-registration.","Confirm the plugin isn't loaded twice via `plugins.config.js` + `package.json` deps.","If you intended to override, use `strapi.middleware('<uid>').extend(fn)` instead of `add()`."],"exampleFix":"// before — collides with core cors middleware\nmodule.exports = {\n  middlewares: { cors: { name: 'cors', handler: () => {} } },\n};\n// after — unique name, or use extend to override\nstrapi.middleware('plugin::myplugin.cors');\n// or rename:\nmodule.exports = {\n  middlewares: { myCors: { name: 'myCors', handler: () => {} } },\n};","handlingStrategy":"validation","validationCode":"function addMiddlewareSafely(strapi, namespace, middlewares) {\n  const existing = new Set(strapi.middleware.keys());\n  for (const name of Object.keys(middlewares)) {\n    const uid = `${namespace}::${name}`; // mirror addNamespace for known prefixes\n    if (existing.has(uid)) {\n      strapi.log.warn(`Skipping duplicate middleware ${uid}`);\n      continue;\n    }\n  }\n  strapi.middleware.add(namespace, middlewares);\n}","typeGuard":"const isMiddlewareRegistered = (strapi, uid: string): boolean =>\n  strapi.middleware.keys().includes(uid);","tryCatchPattern":"try {\n  strapi.middleware.add(namespace, middlewares);\n} catch (e) {\n  if (!String(e.message).includes('has already been registered')) throw e;\n}","preventionTips":["Use unique middleware names prefixed by your plugin.","Don't load the same plugin twice (local + npm).","Use `.extend()` to override an existing middleware rather than re-`add`."],"tags":["middleware","registry","duplicate","lifecycle"],"backgroundTag":null,"analyzedSha":"4a4101264d7098754df36e85fa629fd2f2349d8c","analyzedAt":"2026-08-12T12:47:50.760Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}