Plugin Route path conflict, please try rename the path

Error message

Plugin Route path conflict, please try rename the path

What it means

addPluginRouter() in server/websocket.js throws this when two plugin routes resolve to the same '/ws_plugin/<path>' routePath. routes are tracked in the pluginsRouterPath array and duplicates are rejected to avoid route shadowing.

Source

Thrown at server/websocket.js:18

const koaRouter = require('koa-router');
const interfaceController = require('./controllers/interface.js');
const yapi = require('./yapi.js');

const router = koaRouter();
const { createAction } = require("./utils/commons.js")

let pluginsRouterPath = [];


function addPluginRouter(config) {
  if (!config.path || !config.controller || !config.action) {
    throw new Error('Plugin Route config Error');
  }
  let method = config.method || 'GET';
  let routerPath = '/ws_plugin/' + config.path;
  if (pluginsRouterPath.indexOf(routerPath) > -1) {
    throw new Error('Plugin Route path conflict, please try rename the path')
  }
  pluginsRouterPath.push(routerPath);
  createAction(router, "/api", config.controller, config.action, routerPath, method, true);
}


function websocket(app) {
  createAction(router, "/api", interfaceController, "solveConflict", "/interface/solve_conflict", "get")

  yapi.emitHookSync('add_ws_router', addPluginRouter);


  app.ws.use(router.routes())
  app.ws.use(router.allowedMethods());
  app.ws.use(function (ctx, next) {
    return ctx.websocket.send(JSON.stringify({
      errcode: 404,
      errmsg: 'No Fount.'

View on GitHub (pinned to 59bade3a8a)

Solutions

Rename the path in one of the plugins so each '/ws_plugin/*' path is unique
Check the plugin list in config for duplicate plugin entries and remove one
If caused by hot-reload, guard registration so each plugin registers once per process
Upgrade the conflicting plugin to a version that namespaces its ws routes

Example fix

// before (plugin B)
addPluginRouter({ path: 'status', controller: ctrlB, action: 'get' }); // collides with plugin A
// after (plugin B)
addPluginRouter({ path: 'pluginB/status', controller: ctrlB, action: 'get' });

Defensive patterns

Strategy: validation

Validate before calling

const seen = new Set();
configs.forEach(c => {
  const p = '/ws_plugin/' + c.path;
  if (seen.has(p)) throw new Error(`duplicate ws plugin route: ${p}`);
  seen.add(p);
});

Try / catch

try {
  addPluginRouter(config);
} catch (e) {
  if (/path conflict/.test(e.message)) {
    console.error(`ws route '${config.path}' already registered by another plugin`);
  } else throw e;
}

Prevention

Namespace plugin ws paths with the plugin name (e.g. 'myplugin/status')
Avoid enabling the same plugin twice in the config
If the loader can run twice, track registered routes outside the reload cycle

When it happens

Trigger: Two plugins (or one plugin registering twice) define routes with the same path value, e.g. both register path 'open' so '/ws_plugin/open' collides.

Common situations: Installing two plugins that use the same default route path; enabling the same plugin twice in config; hot-reload re-running plugin registration without clearing pluginsRouterPath; plugin path left as default placeholder.

Related errors

AI-assisted analysis of YMFE/yapi@59bade3a8a (2026-08-29). Data as JSON: /api/errors/902126cdc83e2d7a. Report an issue: GitHub.