How to fix Error: FST_ERR_DEC_ALREADY_PRESENT: Fastify instance already has 'name' decorator in Node.js

Node.jsINTERMEDIATEHIGHUpdated Dec 9, 2025· 127 views

This error occurs in Fastify when you try to register a decorator (plugin, hook, or utility method) with a name that already exists. Fastify prevents duplicate decorator registration to avoid silent overwrites. The fix involves checking for existing decorators, using unique names, or explicitly overwriting when intentional.

Quick fix

Fixes FST_ERR_DEC_ALREADY_PRESENT

Error: FST_ERR_DEC_ALREADY_PRESENT: Fastify instance already has 'myDecorator' decorator
  1. Read the error message carefully
  2. Search for all registrations of the conflicting decorator
  3. Check for duplicate plugin registration
  4. Check plugin export/require paths
node.js — error
Error: FST_ERR_DEC_ALREADY_PRESENT: Fastify instance already has 'myDecorator' decorator
Error: FST_ERR_DEC_ALREADY_PRESENT: Fastify instance already has 'name' decorator

What this error means

Fastify decorators are custom methods, utilities, or properties you add to the Fastify instance, request, or reply objects to extend their functionality. When you attempt to register a decorator with a name that already exists on the target object, Fastify throws this error to prevent accidental data loss or unpredictable behavior from silent overwrites. This is a safety feature: silently replacing an existing decorator could cause bugs that are difficult to debug, especially in large applications with multiple plugins. The error forces you to be explicit about your intentions.

Typical symptoms

  • Application crashes immediately after starting with FST_ERR_DEC_ALREADY_PRESENT error
  • Error message includes the name of the conflicting decorator
  • Problem occurs when loading plugins or initializing Fastify
  • Error happens in server startup or during plugin registration
  • Same decorator name appears to be registered multiple times

Common causes

  1. You are registering the same decorator name twice in different parts of your code
  2. A plugin you are using registers a decorator that conflicts with another plugin
  3. A plugin is being registered multiple times, each attempt registering the same decorator
  4. You are importing and registering the same plugin twice accidentally
  5. There is a naming collision between your custom decorator and a plugin's decorator

How to fix "Error: FST_ERR_DEC_ALREADY_PRESENT: Fastify instance already has 'name' decorator"

1Read the error message carefully

The error message includes the name of the conflicting decorator:

bash
Error: FST_ERR_DEC_ALREADY_PRESENT: Fastify instance already has 'myDecorator' decorator

Note the decorator name (in this example, 'myDecorator'). This tells you exactly what is being duplicated. Check the full error stack trace to see where the duplicate registration is happening.

2Search for all registrations of the conflicting decorator

Search your codebase for where this decorator is being registered:

bash
# Search for fastify.decorate calls
grep -r "fastify.decorate.*myDecorator" .
grep -r "fastify.decorateRequest.*myDecorator" .
grep -r "fastify.decorateReply.*myDecorator" .

# Also search in plugins
grep -r "instance.decorate.*myDecorator" .

Replace 'myDecorator' with your actual decorator name. Make a list of all locations where this decorator is being registered.

3Check for duplicate plugin registration

If you are using plugins, verify that each plugin is registered only once:

javascript
// WRONG: plugin registered twice
await fastify.register(myPlugin);
await fastify.register(myPlugin); // Duplicate!

// CORRECT: plugin registered once
await fastify.register(myPlugin);

Also check your plugin loading code:

javascript
// Bad: loading all files may include duplicates
const files = readdirSync('./plugins');
for (const file of files) {
  await fastify.register(require(`./plugins/${file}`));
}
// If './plugins' contains both 'my-plugin.js' and 'my-plugin/index.js',
// it will be registered twice!
4Check plugin export/require paths

Verify that when you import and register plugins, you are not loading them multiple ways:

javascript
// WRONG: loading same plugin via different paths
const plugin1 = require('./plugin');
const plugin2 = require('./plugin.js');
await fastify.register(plugin1);
await fastify.register(plugin2); // Same plugin, different require path!

// CORRECT: use absolute or consistent relative paths
const plugin = require(path.resolve(__dirname, 'plugin.js'));
await fastify.register(plugin); // Only once
5Use unique decorator names

If you are intentionally creating multiple similar decorators, give them unique names:

javascript
// WRONG: Same name registered multiple times
fastify.decorate('utils', utilsV1);
fastify.decorate('utils', utilsV2); // Conflict!

// CORRECT: Use unique names
fastify.decorate('utils', utilsV1);
fastify.decorate('utilsV2', utilsV2);

// Or namespace them
fastify.decorate('utils', { v1: utilsV1, v2: utilsV2 });
6Check for decorator existence before registering

Use hasDecorator to check if a decorator already exists:

javascript
// Check instance decorators
if (!fastify.hasDecorator('myDecorator')) {
  fastify.decorate('myDecorator', myDecoratorFunction);
}

// Check request decorators
if (!fastify.hasRequestDecorator('userId')) {
  fastify.decorateRequest('userId', null);
}

// Check reply decorators
if (!fastify.hasReplyDecorator('sendCustom')) {
  fastify.decorateReply('sendCustom', function() { /* ... */ });
}

This allows safe idempotent registration, useful in testing or dynamic scenarios.

7Override existing decorators if intentional

If you genuinely want to replace an existing decorator (e.g., mocking in tests), use the decorate methods with the override option:

javascript
// Override an existing decorator
fastify.decorate('myDecorator', newImplementation, true);

// Third parameter true allows overriding
fastify.decorateRequest('userId', newValue, true);
fastify.decorateReply('sendCustom', newFunction, true);

Be cautious with this approach - only override when you're certain about the implications.

8Review plugin conflicts

If the conflict is between two plugins, check their code:

javascript
// In plugin-a.js
module.exports = async (fastify) => {
  fastify.decorate('db', dbInstance);
};

// In plugin-b.js
module.exports = async (fastify) => {
  fastify.decorate('db', anotherDbInstance); // Conflict!
};

Solutions:
1. Only load one of the conflicting plugins
2. Ask the plugin maintainers to use different names
3. Fork and modify one plugin to use a different name
4. Use decorator scope (decorate different parts: fastify, request, reply) if both are needed

9Test your fix

After fixing the duplicate registration, start your application to verify the error is gone:

bash
# Start the application
node index.js

# Or with npm
npm start

The application should start without the FST_ERR_DEC_ALREADY_PRESENT error. If you're using tests:

bash
npm test

Ensure all tests pass and the decorator is available where expected.

Advanced notes

Decorator scopes: Fastify has three different decorator scopes. They are independent, so you can have the same name in different scopes:

javascript
fastify.decorate('data', 'instance-level');         // On fastify instance
fastify.decorateRequest('data', 'request-level');   // On request object
fastify.decorateReply('data', 'reply-level');       // On reply object

// Each scope maintains separate decorators, so no conflict

Plugin scoping: If a plugin should only decorate instances of itself (not the parent fastify instance), use plugin scoping:

javascript
module.exports = async (fastify, options) => {
  // This decoration is scoped to this plugin's context
  fastify.decorate('pluginSpecificHelper', helperFunction);
};

Fastify versioning: Different Fastify versions may have different behavior around decorators. Always ensure your plugins are compatible with your Fastify version. Check the plugin's peerDependencies in package.json.

Testing tip: When testing Fastify applications with decorators, be aware that the test fastify instance is separate from your application instance. Decorators added in one test don't carry over to another unless you're reusing the same instance.

Performance consideration: Decorators are looked up by name on every access, so naming them clearly and avoiding excessive numbers of decorators is a best practice for maintainability, not performance.

Frequently asked questions

What does "FST_ERR_DEC_ALREADY_PRESENT" mean?
Fastify decorators are custom methods, utilities, or properties you add to the Fastify instance, request, or reply objects to extend their functionality. When you attempt to register a decorator with a name that already exists on the target object, Fastify throws this error to prevent accidental data loss or unpredictable behavior from silent overwrites. This is a safety feature: silently replacing an existing decorator could cause bugs that are difficult to debug, especially in large applications with multiple plugins.
How do I fix "FST_ERR_DEC_ALREADY_PRESENT"?
This error occurs in Fastify when you try to register a decorator (plugin, hook, or utility method) with a name that already exists. Fastify prevents duplicate decorator registration to avoid silent overwrites. The fix involves checking for existing decorators, using unique names, or explicitly overwriting when intentional.
What causes "FST_ERR_DEC_ALREADY_PRESENT"?
You are registering the same decorator name twice in different parts of your code A plugin you are using registers a decorator that conflicts with another plugin A plugin is being registered multiple times, each attempt registering the same decorator
Is the "FST_ERR_DEC_ALREADY_PRESENT" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading