NITRO0025Register Nitro handlers and plugins with absolute paths
Why it happens
Nitro does not resolve a registered path against the file that registers it. Nitro 2 and Nitro 3 resolve handler and plugin paths against Nitro’s project rootDir. A generated file written to resolve(root, '.vitehub/handler.ts') but registered as '.vitehub/handler.ts' only works while every root happens to match, and it breaks for monorepos, custom srcDir or Vite roots, and Nitro 2.
Fix
Register the same absolute path you write the file to, for example resolve(root, '.generated/handler.ts'), or resolve files shipped with the package with createResolver(import.meta.url). Doctor checks files that import from vite, nitro, nitropack, @nuxt/kit or @nuxt/schema, and skips config files, tests, app and server runtime directories, and arguments of @nuxt/kit helpers, which nuxt/module/resolve-runtime-paths reports. It checks relative literals and const paths in handler objects with a route, middleware, method or lazy key, and in Nitro plugins arrays. For addPlugin and addServerPlugin calls on builders created by named imports of createNitroServerKit or createNitroConfigKit, Doctor compares an explicit Nitro root with writes on the registration path, including straight-line writes in awaited local helpers. It skips the Diagnostic when a competing write might already reach Nitro's destination. When the Nitro options come from a parameter, Doctor also checks separate helpers that share the same path constant when there is a single matching write and the roots come from separate inputs that can diverge.
Example
Register generated handlers with the path they were written to
Before
const middleware = '.generated/nitro/middleware.ts'
await writeFile(resolve(root, middleware), code)
nitroConfig.handlers.push({ handler: middleware, middleware: true })
After
const middleware = resolve(root, '.generated/nitro/middleware.ts')
await writeFile(middleware, code)
nitroConfig.handlers.push({ handler: middleware, middleware: true })
Verify the fix
Run only this rule after editing so the report stays focused on the diagnostic you are closing:
pnpm vite-doctor . --framework nitro --rules nitro/config/require-absolute-generated-paths