What causes "The decorator is missing dependency '%s'." in fastify/fastify?

Register the dependency decorator first: app.decorate('session', ...); then app.decorate('cart', ..., ['session']).

fastify/fastify · error · Error

FST_ERR_DEC_MISSING_DEPENDENCY

FST_ERR_DEC_MISSING_DEPENDENCY

Error message

The decorator is missing dependency '%s'.

What it means

Thrown by checkDependencies() (decorate.js:124) when a name listed in the dependencies array does not exist on the instance (checked via checkExistence). It enforces ordering: if decorator 'cart' depends on 'session', 'session' must already be registered before 'cart' is added.

Source

Thrown at lib/decorate.js:125

function checkReplyExistence (name) {
  if (name && hasKey(this[kReply], name)) return true
  if (name && hasInstanceProperty(this[kReply], name)) return true
  return checkExistence(this[kReply].prototype, name)
}

function checkDependencies (instance, name, deps) {
  if (deps === undefined || deps === null) {
    return
  }

  if (!Array.isArray(deps)) {
    throw new FST_ERR_DEC_DEPENDENCY_INVALID_TYPE(name)
  }

  for (let i = 0; i !== deps.length; ++i) {
    if (!checkExistence(instance, deps[i])) {
      throw new FST_ERR_DEC_MISSING_DEPENDENCY(deps[i])
    }
  }
}

function decorateReply (name, fn, dependencies) {
  assertNotStarted(this, name)
  checkReferenceType(name, fn)
  decorateConstructor(this[kReply], name, fn, dependencies)
  return this
}

function decorateRequest (name, fn, dependencies) {
  assertNotStarted(this, name)
  checkReferenceType(name, fn)
  decorateConstructor(this[kRequest], name, fn, dependencies)
  return this
}

View on GitHub (pinned to 7299a57d3f)

Solutions

Register the dependency decorator first: app.decorate('session', ...); then app.decorate('cart', ..., ['session']).
Inside plugins, use avvio's boot ordering: register the dependency-providing plugin before the dependent plugin in the fastify.register chain.
Verify the dependency name spelling matches exactly (case-sensitive).
If the dependency is optional, drop it from the array and check existence at runtime via hasDecorator.

Example fix

// before
app.decorate('cart', getCart, ['session']) // 'session' missing => throws

// after
app.decorate('session', getSession)
app.decorate('cart', getCart, ['session'])

Defensive patterns

Strategy: validation

Validate before calling

function decorateWithDeps(app, name, value, deps) {
  const missing = (deps || []).filter(d => !app.hasDecorator(d))
  if (missing.length) {
    throw new Error('Missing decorators: ' + missing.join(', '))
  }
  app.decorate(name, value, deps)
}

Type guard

function depsAvailable(app, deps) {
  return (deps || []).every(d => app.hasDecorator(d))
}

Try / catch

try {
  app.decorate('cart', getCart, ['session'])
} catch (err) {
  if (err.code === 'FST_ERR_DEC_MISSING_DEPENDENCY') {
    app.decorate('session', getSession)
    app.decorate('cart', getCart, ['session'])
  } else throw err
}

Prevention

Register dependency decorators before dependent ones in the boot chain.
Use app.hasDecorator(d) to validate before calling decorate when deps are optional.
Keep a topological ordering of decorator registration in your bootstrap code.

When it happens

Trigger: Calling fastify.decorate('cart', fn, ['session']) before 'session' has been registered; a typo in a dependency name; dependency declared but its providing plugin not yet registered in the boot chain.

Common situations: Plugin load order issues where the consumer registers the dependent decorator before the dependency; refactoring that splits decorators into plugins without updating order; optional dependencies that aren't always loaded.

Related errors

AI-assisted analysis of fastify/fastify@7299a57d3f (2026-08-03). Data as JSON: /data/errors/20643faf7bfb36df.json. Report an issue: GitHub.