{"id":30,"type":"blog","title":"What Broke When I Deployed Next.js 16 to Heroku","slug":"what-broke-deploying-nextjs-16-heroku","canonicalUrl":"https://docs.phatysd.me/content/what-broke-deploying-nextjs-16-heroku","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"Web Blog > Engineering Journal > Deployment","topics":["Heroku","Next.js 16","Production debugging"],"tags":["heroku","nextjs","deployment","debugging","postmortem"],"related":[{"slug":"deployment-runbook-heroku-cloudflare","title":"Deployment Runbook: Heroku + Cloudflare","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare"},{"slug":"heroku-postgres-drizzle-operations","title":"Heroku Postgres + Drizzle Operations","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/heroku-postgres-drizzle-operations"}],"body":"# What Broke When I Deployed Next.js 16 to Heroku\n\nThe 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.\n\n## Failure one: Postgres worked locally but not in production\n\nThe 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.\n\nThe 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.\n\n## Failure two: the port in the log was not a public URL\n\nHeroku 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`.\n\nThis distinction matters for OAuth too. A callback constructed from an internal port can never be a stable public callback.\n\n## Failure three: public environment values needed a fresh build\n\nThe 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`.\n\n## The verification loop\n\nThe final release gate was not “Heroku says deployed.” It was:\n\n```bash\nnpm run typecheck\nnpm run lint\nnpm run build\ncurl -fsS -o /dev/null -w '%{http_code}\\n' https://docs.phatysd.me/\ncurl -fsS -o /dev/null -w '%{http_code}\\n' https://docs.phatysd.me/llms.txt\ncurl -fsS -o /dev/null -w '%{http_code}\\n' https://docs.phatysd.me/content/<slug>/json\n```\n\nThen came the browser OAuth flow and a database-backed read. Each command tested a different boundary.\n\n## What I would do earlier next time\n\nI 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.\n\n## References\n\n- [Next.js deployment](https://nextjs.org/docs/app/getting-started/deploying)\n- [Heroku application lifecycle](https://devcenter.heroku.com/articles/heroku-application-lifecycle)\n- [Heroku config vars](https://devcenter.heroku.com/articles/config-vars)\n- [Heroku releases](https://devcenter.heroku.com/articles/releases)\n"}