How to fix Error: FST_ERR_PLUGIN_ALREADY_REGISTERED: Plugin already registered in Node.js

Node.jsINTERMEDIATEHIGH

This error occurs when you attempt to register the same Fastify plugin multiple times, either directly in your code or through a chain of dependencies. Fastify prevents duplicate plugin registration to avoid conflicts, state duplication, and unpredictable behavior.

What this error means

Fastify maintains an internal registry of all loaded plugins to ensure each plugin is initialized exactly once per Fastify instance. When you try to register a plugin that Fastify has already loaded, it throws this error to prevent duplicate initialization, which could cause: - State conflicts (plugins maintaining internal state would have duplicate instances) - Memory leaks (resources allocated by the first plugin instance not being cleaned up) - Unexpected behavior (hooks, routes, or decorators being registered twice) - Race conditions (plugins modifying shared state simultaneously) This is a safety mechanism, not a sign of the plugin itself being broken. The issue is in how the application is loading the plugin.

How to fix "Error: FST_ERR_PLUGIN_ALREADY_REGISTERED: Plugin already registered"

1Identify which plugin is causing the duplicate registration

The error message should include the plugin name. Look at your Fastify initialization code to find where you register plugins:

javascript

const fastify = require('fastify')();

// The error will mention which of these plugins is registered twice
fastify.register(require('@fastify/cors'));
fastify.register(require('@fastify/jwt'));
fastify.register(require('./my-custom-plugin'));

If the error message is vague, add logging to see the exact sequence of plugin registrations:

javascript

fastify.addHook('onRegister', (instance, opts) => {
  console.log('Plugin registered:', opts);
});

2Check for direct duplicate registrations in your code

Search for the problematic plugin name across your project to find all registration points:

bash

# Search for plugin registration
grep -r "@fastify/cors" src/
grep -r "register(" src/

Each plugin should be registered exactly once. Example of what to avoid:

javascript

// ❌ Wrong - plugin registered twice
fastify.register(require('@fastify/cors'));
// ... more code ...
fastify.register(require('@fastify/cors')); // Duplicate!

// ✅ Correct - plugin registered once
fastify.register(require('@fastify/cors'));

3Check for indirect duplicates through imports

Sometimes the same plugin is registered through different module imports:

javascript

// app.js
const plugin = require('./my-plugin');
fastify.register(plugin);

// routes/api.js - imported by app.js
const plugin = require('./my-plugin');
fastify.register(plugin); // Same plugin, different import!

Move plugin registration to a single location and pass the fastify instance where needed:

javascript

// app.js - single registration
const plugin = require('./my-plugin');
fastify.register(plugin);

// routes/api.js - no plugin registration
module.exports = async (fastify) => {
  // Use plugin features without re-registering
  fastify.myDecorator(); // Plugin already loaded
};

4Resolve dependency conflicts

If the error appears after updating dependencies, it may be a transitive dependency issue. Check your package.json and dependency tree:

bash

# List all versions of a package in your dependency tree
npm list @fastify/cors

# Look for duplicates - should show only one version

If you see multiple versions, pin to a single version in package.json:

json

{
  "dependencies": {
    "@fastify/cors": "^8.0.0",
    "some-package": "^1.0.0"
  }
}

Then reinstall:

bash

rm -rf node_modules package-lock.json
npm install

5Ensure proper cleanup in tests

If this error occurs during testing, ensure you properly close the Fastify instance between tests:

javascript

// ❌ Wrong - fastify instance reused
let fastify;
beforeAll(() => {
  fastify = require('fastify')();
  fastify.register(require('@fastify/cors'));
});

afterEach(() => {
  // Not closing fastify!
});

test('test 1', () => {
  // fastify still has the plugin from test setup
});

Instead, create a fresh instance per test:

javascript

// ✅ Correct - fresh instance per test
beforeEach(async () => {
  fastify = require('fastify')();
  fastify.register(require('@fastify/cors'));
  await fastify.ready();
});

afterEach(async () => {
  await fastify.close();
});

6Use named routes to avoid plugin conflicts

If you're registering plugins in nested route contexts, use the prefix option to isolate them:

javascript

// Register plugin once at root level
fastify.register(async (instance) => {
  // All sub-routes inherit this plugin
  instance.decorateRequest('user', null);
});

// Bad - trying to re-register in a sub-route
fastify.register(async (instance) => {
  instance.register(require('@fastify/cors')); // OK here
  
  instance.register(async (subInstance) => {
    // Don't re-register parent plugins here
  });
});

// Good - use existing decorators in nested routes
fastify.register(async (parentInstance) => {
  parentInstance.register(require('@fastify/cors'));
  
  parentInstance.register(async (subInstance) => {
    // Decorators from parent are inherited
    subInstance.get('/', (req, res) => {
      // Can use req.user from parent plugin
    });
  });
});

How to fix Error: FST_ERR_PLUGIN_ALREADY_REGISTERED: Plugin already registered in Node.js

What this error means

Typical symptoms

Common causes

How to fix "Error: FST_ERR_PLUGIN_ALREADY_REGISTERED: Plugin already registered"

Advanced notes

Related errors

Official resources & further reading