Nuxt Build Errors on Cloudflare Pages

Deploying a Nuxt 3 app to Cloudflare Pages sounds like a dream: fast builds, free CDN, and tight Git integration. But sometimes, the dream gets a little rocky—especially when your final deploy step throws a confusing error like:

"Build output directory contains links to files that can't be accessed"

If you've ever been stumped by this vague message, you're not alone. Here's a quick breakdown of what it means, what causes it, and how to fix it.

The Mystery Error

When deploying a Nuxt 3 app to Cloudflare Pages, everything seems to go smoothly:

• The Nuxt build completes successfully
• Nitro prerenders all your routes
• Fonts are downloaded and cached
• .output/public is generated

But then Cloudflare checks your build output and—boom—deployment fails with the "links that can't be accessed" error.

This typically means that the final output folder (.output/public, in Nuxt's case) contains symbolic links or references to files outside the directory, which Cloudflare can't resolve in its static environment.

The Fix (Step by Step)

1. Set the Right Output DirectoryIn the Cloudflare Pages dashboard:This tells Cloudflare where to look after the build completes.
   • Set the Output Directory to .output/public

(Optional) Improve PrerenderingIf you're building a mostly static site (no server-side API calls), you can also specify routes to ensure everything gets prerendered:

export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages',
    prerender: {
      crawlLinks: true,
      routes: ['/', '/about', '/contact'] // Add any static routes you have
    }
  }
})

Avoid Symbolic Links or External File ReferencesNuxt modules (like font loaders, image transformers, or server utilities) may create symbolic links or try to read runtime files. These don't work in Cloudflare's read-only, static environment.To reset things:

rm -rf .output .nuxt node_modules
pnpm install
pnpm build

Then redeploy.

Use the Correct Nitro PresetIn your nuxt.config.ts, be sure you're using the cloudflare-pages preset:

export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages'
  }
})

This ensures your app is tailored for Cloudflare's static hosting model, placing all output in .output/public.

Final Thoughts

This issue is one of those sneaky deployment quirks that feels obscure until you've hit it yourself. But once you know it's about symbolic links and misconfigured outputs, it's easy to sidestep.

So if you're using Nuxt 3 and Cloudflare Pages and bump into this error, take a breath, follow the checklist, and you'll be live in no time.

Have you faced weird errors when deploying Nuxt apps to Cloudflare, Vercel, or Netlify? Share them below and let's figure them out together.