Clerk + Fastify: scope clerkPlugin() to the routes that need it

TL;DR

Use Fastify's encapsulation: register the plugin inside a scoped context for the routes that need auth, and leave public routes outside it. `ts // public: no auth fastify.post('/api/webhooks', webhookHandler) fastify.get('/health', async () => ({ ok: true })) // authenticated area fastify.register(async (instance) => { instance.register(clerkPlugin) instance.get('/protected', async (request, reply) => { const { isAuthenticated, userId } = getAuth(request) if (!isAuthenticated) { return reply.code(401).send({ error: 'User not authenticated' }) } //... }) })

// public: no auth
fastify.post('/api/webhooks', webhookHandler)
fastify.get('/health', async () => ({ ok: true }))

// authenticated area
fastify.register(async (instance) => {
  instance.register(clerkPlugin)
  instance.get('/protected', async (request, reply) => {
    const { isAuthenticated, userId } = getAuth(request)
    if (!isAuthenticated) {
      return reply.code(401).send({ error: 'User not authenticated' })
    }
    // ...
  })
})

Steps

1. Use Fastify's encapsulation: register the plugin inside a scoped context for the routes that need auth, and leave public routes outside it.

// public: no auth
fastify.post('/api/webhooks', webhookHandler)
fastify.get('/health', async () => ({ ok: true }))

// authenticated area
fastify.register(async (instance) => {
 instance.register(clerkPlugin)
 instance.get('/protected', async (request, reply) => {
 const { isAuthenticated, userId } = getAuth(request)
 if (!isAuthenticated) {
 return reply.code(401).send({ error: 'User not authenticated' })
 }
 // ...
 })
})

When to use

You are seeing this: fastify.register(clerkPlugin) at the top level applies auth state attachment to every route in that context, including /health, /metrics, and webhook endpoints that must stay public. Use this skill when you run into "Clerk + Fastify: scope clerkPlugin() to the routes that need it".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

Gating them breaks delivery and triggers retries. - Health and readiness probes from your platform get no session either; auth overhead on them is pure latency. - getAuth() outside a plugin-registered context has no auth state to read.

Clerk's Fastify quickstart registers clerkPlugin for all routes and points to the clerkPlugin() reference for per-route protection; the webhooks debugging guide requires webhook routes to stay public. Verified live at https://clerk.com/docs/fastify/getting-started/quickstart.md and https://clerk.com/docs/guides/development/webhooks/debugging.md on 2026-09-26.