Works Locally, Fails After Deployment

The Production Bugs That Never Threw an Error was about systems that reported success while running the wrong thing. 200 OK, Data Wrong was about APIs that returned clean responses with incorrect output. These four are different — the code was correct, the build passed, but the deploy target had constraints that only surfaced in production.

The File That Wasn't Bundled

Local dev worked. Preview builds worked. The production deployment threw a runtime error trying to read a file that was clearly in the repository.

Vercel's build system uses output file tracing to determine which files a deployment actually needs. When the path to a file is computed at runtime — built from variables, not a literal string — the tracer can't detect the dependency. The file gets left out of the deployment bundle.

// next.config.js
experimental: {
  outputFileTracingIncludes: {
    '/api/report': ['./data/templates/**/*'],
  },
}

Any file read with a computed path needs to be declared here. The tracer won't find it on its own.

The Path That Moved

A Cloud Run service authenticated with a service account JSON file. Locally I used a relative path — ./service-account.json — and it resolved fine because the working directory was my project root. In Cloud Run, if the Dockerfile doesn't set WORKDIR, the container starts in /. The relative path resolved to somewhere that didn't exist, and the error came back as a generic authentication failure rather than a file-not-found.

import path from 'path';

const keyFile = path.resolve(__dirname, 'service-account.json');

__dirname is the directory of the compiled file, which is stable regardless of where the process is invoked from.

The Routes That Vanished

A CDK stack had a CloudFront distribution with behaviors for several path patterns. /api/* was supposed to route to a Lambda. /* was a fallback to S3. After a deploy, API routes started returning S3 content instead of Lambda responses.

CloudFront applies behaviors in the order they're defined in the array. /* had been added first, and it matched everything — including /api/* — before the more specific pattern had a chance to evaluate. CDK doesn't validate or sort behavior order. Specific patterns first, catch-all last.

The OG Image That Disappeared

Three bugs stacked on one OG image. First: I was rendering at 1200x600. Facebook needs 1200x630 for a full-size preview — anything smaller renders as a tiny thumbnail or gets skipped entirely. Neither platform logs an error. I discovered it by running the URL through Twitter's Card Validator after a campaign showed zero image previews.

Second: the image used CSS Grid layout, clip-path, and backdrop-filter. In the browser it looked right. Satori — the library Next.js uses to render opengraph-image.tsx server-side — only supports a subset of CSS. No display: grid. No pseudo-elements. No clip-path. No backdrop-filter. When it encounters something it doesn't support it doesn't throw — it silently skips the rule or collapses the element.

Third: after fixing dimensions and CSS, I redeployed. Twitter still showed the old version. Social platforms cache OG tags aggressively — Twitter for up to a week, Facebook for days. Redeploying does nothing. The only way to force a re-fetch is through each platform's debug tool.

What They Share

Local dev doesn't have a file tracer. It doesn't change the working directory between builds. It doesn't apply CDN behavior ordering. It doesn't validate OG dimensions or enforce a CSS subset.

Every one of these bugs lived in the gap between what local dev simulates and what production actually enforces. The build passing tells you the code compiles. It tells you nothing about whether the deploy target will accept it.