Postmortem: Nuxt Content 404s on Staging Deployments

1. The Issue

• Symptom: Direct URLs or page reloads to /blog/* and /help/* threw a 404 error in the Staging environment.
• Impact: Content routing in Staging was broken for direct links.

2. Root Cause

• Empty Database: The Staging Cloudflare D1 database was completely empty. It lacked all Nuxt Content tables.
• My Mistake: I failed to understand that NuxtHub requires the specific nuxthub deploy CLI command to automatically sync the database.
• Because I was using the vanilla wrangler deploy command in my package.json scripts, the automated database synchronization was entirely bypassed, leaving the Staging database empty.

3. Why It Was Confusing

The issue was masked by an illusion that client-side navigation was working:

• Index Pages (/blogs): Code used .all(). Against an empty database, it returned []. The page loaded successfully but silently displayed 0 posts.
• Individual Posts (/blog/post-name): Code used .first(). Against an empty database, it returned null, which explicitly triggered a 404 error page.

4. The Fix

• Immediate: Manually synced the Staging database using the generated SQL dump:

  wrangler d1 execute project-staging --remote --file .nuxt/content/sql_dump.txt
  

• Long-term: Hardcoded the database synchronization step directly into the package.json deployment scripts to ensure the deployment command always seeds the D1 database moving forward.