Blog · Web Blog / Engineering Journal / Deployment

What Broke When I Deployed Next.js 16 to Heroku

What Broke When I Deployed Next.js 16 to Heroku

The first production deploy looked simple: build a Next.js 16 App Router project, attach Heroku Postgres, configure GitLab OAuth, and put Cloudflare in front of the custom domain. The failures were not all application bugs. They were boundary bugs between build-time configuration, dyno runtime, TLS, and the public URL.

Failure one: Postgres worked locally but not in production

The local database connection did not behave like the Heroku connection. Heroku Postgres expects an SSL-capable connection path, while the initial postgres-js client was created without an explicit production SSL policy. The application could build, but a database-backed request failed at runtime.

The fix was deliberately small: keep local connections non-SSL where appropriate, but use ssl: "require" in production unless the connection string explicitly disables SSL. The important lesson is that next build does not exercise every database query. A production route smoke test is required.

Failure two: the port in the log was not a public URL

Heroku logs exposed the dyno's internal listening port. That port is assigned by the platform and is not something a user should paste into a browser or OAuth provider. The public address is the Heroku hostname or configured custom domain; the application must listen on the platform-provided PORT.

This distinction matters for OAuth too. A callback constructed from an internal port can never be a stable public callback.

Failure three: public environment values needed a fresh build

The app used NEXT_PUBLIC_SITE_URL to construct canonical URLs. Setting the config var at runtime restarted the app, but the generated public value could still reflect the environment used when the build artifact was created. The safe fix was to set the value before a fresh build and verify the emitted canonical URL, JSON representation, and llms.txt.

The verification loop

The final release gate was not “Heroku says deployed.” It was:

npm run typecheck
npm run lint
npm run build
curl -fsS -o /dev/null -w '%{http_code}\n' https://docs.phatysd.me/
curl -fsS -o /dev/null -w '%{http_code}\n' https://docs.phatysd.me/llms.txt
curl -fsS -o /dev/null -w '%{http_code}\n' https://docs.phatysd.me/content/<slug>/json

Then came the browser OAuth flow and a database-backed read. Each command tested a different boundary.

What I would do earlier next time

I would write the public-origin contract first, make the database SSL policy explicit from the first commit, and test the deployed custom hostname before debugging the browser UI. The shortest path was not more logging; it was a smaller feedback loop that exercised the actual production boundary.

References

Agent access

Choose a representation.

Published content only
Human pageYou are reading the human-facing canonical page.
Current page

Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.