---
id: 30
type: blog
title: "What Broke When I Deployed Next.js 16 to Heroku"
slug: "what-broke-deploying-nextjs-16-heroku"
canonical_url: "https://docs.phatysd.me/content/what-broke-deploying-nextjs-16-heroku"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "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
    canonical_url: "https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare"
  - slug: "heroku-postgres-drizzle-operations"
    title: "Heroku Postgres + Drizzle Operations"
    type: docs
    canonical_url: "https://docs.phatysd.me/content/heroku-postgres-drizzle-operations"
---

# 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:

```bash
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

- [Next.js deployment](https://nextjs.org/docs/app/getting-started/deploying)
- [Heroku application lifecycle](https://devcenter.heroku.com/articles/heroku-application-lifecycle)
- [Heroku config vars](https://devcenter.heroku.com/articles/config-vars)
- [Heroku releases](https://devcenter.heroku.com/articles/releases)
