Nuxt 3 deployment fails at start with 'Cannot find module' for an @/ alias — which log phase to trust

Answer

The authoritative place to confirm the missing @/ alias is the runtime log when you start the Nitro server (node .output/server/index.mjs). The build phase shows no warning because Vite resolves the alias for client code, but Nitro does not automatically apply the same alias for server‑side modules unless it is declared explicitly.

Confirmed facts

• During nuxt build Vite processes client bundles and resolves @/ using the default mapping (./src when a src folder exists).
• Nitro’s server bundle is generated separately; it only honors aliases that are declared in nuxt.config.ts under build.aliases or via tsconfig.json compilerOptions.paths.
• If the alias is missing for server code, the build succeeds without warnings; the error appears only when the server bundle tries to import the module at startup.
• Running node .output/server/index.mjs reproduces the exact Cannot find module '@/utils/config' error, making the runtime log the definitive diagnostic source.

Steps to verify locally

1. Ensure the project builds: nuxt build (should exit with code 0).
2. Start the produced server: node .output/server/index.mjs.
3. Observe stderr; you will see the module‑not‑found error if the alias is not configured for Nitro.
4. To fix, add an explicit alias in nuxt.config.ts:

export default defineNuxtConfig({
  build: {
    aliases: {
      '@/': './src'
    }
  }
})

Alternatively, add a paths entry in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

After adding the alias, repeat nuxt build and node .output/server/index.mjs; the server should start without the module error.

What to ask next (if needed)

If you are using a custom src layout or a monorepo, confirm the exact path you want @/ to point to; otherwise the above steps are sufficient.