AWS Builder Center

Builder Center

Deploy Next.js (App Router) to Vercel with Aurora Serverless — pitfalls & fixes

Common problems when pairing Vercel App Router with a private Aurora DB and practical fixes to keep builds reliable.

Abdelrazek Rizk

Cloud and Data Analytics Specialist

Common problems when pairing Vercel App Router with a private Aurora DB and practical fixes to keep builds reliable.



Problem summary

Next.js prerenders pages at build time or during server-side rendering. If your database initialization code tries to connect during module import, the build will fail when the DB is unreachable (time out, auth error). In addition, Vercel cannot directly access a private VPC — that complicates running migrations and runtime DB access.
This article shares proven patterns to make your Next.js build and runtime robust while using Aurora Serverless.
This article was created for the purposes of entering the H0 hackathon and is based on experiences from the project repository. See Part One:  Run Postgres migrations from anywhere using AWS RDS Data API  

Key fixes and patterns

1) Lazy-init DB (safe stubs at import time)

  • In  src/lib/db.ts  export safe functions that return no-op implementations when env is missing.
  • Only create a real connection pool when  process.env.DATABASE_URL  exists at runtime.
Example (concept):
let pool = null;

if (process.env.DATABASE_URL) {

  pool = new Pool({ connectionString: process.env.DATABASE_URL });

}

export async function query(sql, params) {

  if (!pool) return { rows: [] };

  return pool.query(sql, params);

}
This prevents build-time imports from attempting network connections.

2) Move client-only logic into client components

Hooks such as  useSearchParams  or  useRouter  can cause server-side usage errors. Place interactive behavior into client components (using  'use client' ) and keep server components pure.

3) Migrations & DB in CI

  • Short-term: add a temporary  DATABASE_URL  to Vercel pointing at a test DB that is reachable from Vercel (not recommended for prod).
  • Preferred: configure OIDC trust between Vercel (or GitHub Actions) and AWS and use a role to assume permissions or run migrations inside the VPC with SSM/self-hosted runner.
  • The H0 repo includes  scripts/run-migrations-dataapi.js  for Data API and a runbook for EC2 bastion usage.

4) Add resilience & observability

  • On DB errors, return safe fallback responses for build-time (so  next build  completes), but add CI smoke tests that fail if the DB is required in production.
  • Log database errors with structured logs and ensure not to leak secrets.

Quick checklist before deploying

  • Build locally without DB:  npm run build  should succeed even if DATABASE_URL is not set.
  • Ensure migrations can run in CI (Data API or SSM).
  • Add a smoke test job to CI to run quickly after migrations.

Troubleshooting common errors

  •  ECONNREFUSED  during build — ensure DB is not contacted at import time.
  •  password authentication failed for user "postgres"  — verify Secrets Manager secret contents and that you use the correct username/password or IAM token usage.
  •  DatabaseResumingException  — Aurora Serverless may be auto-paused; wait for it to resume before running statements.

Final notes

Apply the lazy-init and Data API approaches to keep Vercel build and runtime safe. The H0 repo includes example scripts, a runbook, and migration files you can re-use.

"This article was created for the purposes of entering the AWS & Vercel/v0 #H0hackathon."
# serverless# vercel# nextjs
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article