Plugin Route path conflict, please try rename the path

Error message

Plugin Route path conflict, please try rename the path

What it means

addPluginRouter keeps a registry (pluginsRouterPath) of already-registered '/plugin/<path>' routes; registering the same computed routerPath twice throws this conflict error. Prevents two plugin routes from shadowing each other.

Source

Thrown at server/router.js:595

      action: 'importData',
      path: 'import_data',
      method: 'post'
    }
  ]
};

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 = '/plugin/' + config.path;
  // 支持 /api/open/plugin 前缀的 openApi
  let routerPath = (config.prefix || '') + '/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, false);
}

yapi.emitHookSync('add_router', addPluginRouter);

for (let ctrl in routerConfig) {
  let actions = routerConfig[ctrl];
  actions.forEach(item => {
    let routerController = INTERFACE_CONFIG[ctrl].controller;
    let routerPath = INTERFACE_CONFIG[ctrl].prefix + item.path;
    createAction(router, '/api', routerController, item.action, routerPath, item.method);
  });
}

module.exports = router;

View on GitHub (pinned to 59bade3a8a)

Solutions

Rename one plugin's route path so routerPaths are unique.
Remove duplicate plugin entries in config.json.
Use a distinct config.prefix for one of the conflicting routes (e.g. '/api/open').

Example fix

// before
addPluginRouter({ path: 'report', controller: 'a', action: 'get' });
addPluginRouter({ path: 'report', controller: 'b', action: 'get' }); // conflict
// after
addPluginRouter({ path: 'report', controller: 'a', action: 'get' });
addPluginRouter({ path: 'report-v2', controller: 'b', action: 'get' });

Defensive patterns

Strategy: validation

Validate before calling

const seen = new Set();
function routeKey(cfg) { return (cfg.prefix || '') + '/plugin/' + cfg.path; }
// before emitting:
const key = routeKey(cfg);
if (seen.has(key)) throw new Error(`Duplicate plugin route: ${key}`);
seen.add(key);

Try / catch

try {
  yapi.emitHookSync('add_router', addPluginRouter);
} catch (e) {
  if (e.message.includes('path conflict')) {
    console.error('Two plugins registered the same /plugin/<path>; rename one');
  } else { throw e; }
}

Prevention

Namespace plugin route paths with the plugin name (path: 'myplugin/report').
Ensure each plugin appears only once in config.json.
Keep a registry of used plugin route paths when managing many plugins.

When it happens

Trigger: Two plugins (or one plugin twice) define routes resolving to the same (prefix + '/plugin/' + path) string, e.g. both register path 'report' without distinct prefixes.

Common situations: Same plugin listed twice in config.json, two third-party plugins choosing identical route paths, plugin registered for both normal and open API prefixes incorrectly duplicating paths.

Related errors

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