Make deployment checks catch errors your local build misses

A local production build succeeds, but the deployed article route returns an error. The developer's laptop has a database variable, a writable directory, and a Node runtime. The deployment has a missing secret and a route configured for a different runtime. Compilation verified syntax and module relationships; it did not prove that the intended user journey could run with deployment configuration.

This walkthrough assumes Next.js 15 App Router and a project on 15.1.11. It treats deployment checks as evidence for specific behaviors. It does not assume that a successful framework build exercises every dynamic route, external provider, or storage permission. Record what each check actually covers.

Turn one user journey into checks

Choose a public article request because it crosses configuration, data access, rendering, and metadata. Define its expected response: a published record is readable, a missing slug follows the intended missing path, and a dependency outage produces an operational failure. Add an authenticated editing journey if the deployment supports publishing.

List the resources needed by those journeys: database origin, credential, network route, runtime APIs, and any external image or storage provider. Keep this list tied to actual code. An AI assistant can enumerate imports and environment variable names, but it should not invent services from a generic deployment template.

Identify checks that can run without secrets and checks that require an isolated environment. Static type checking can verify contracts. A build can verify packaging. A smoke request can verify a live dependency path. Treat these as complementary rather than interchangeable badges.

Validate configuration without exposing it

Check required variable presence and basic shape at the appropriate startup or execution boundary. Report variable names and safe reasons, never secret values. A database connection string can be present but malformed; a public origin can be syntactically valid but point to a preview domain.

In Next.js, variables intended for browser exposure use the public prefix, and public values can be inlined at build time. A secret should not receive that prefix merely to make a browser component work. If a deployment artifact moves between environments, consider whether a build-time public value has already been frozen into it.

Separate build requirements from runtime requirements. A static article generation path may need database access during the build. A dynamic route may need it only while serving requests. Decide which model the application intends and test it explicitly, rather than making every build depend on production storage by accident.

Check the runtime boundary

Inspect route configuration and imported libraries. A database driver using Node APIs may not run in an Edge runtime. A generated helper can import filesystem or crypto functionality indirectly through a utility barrel. Find the actual dependency rather than assuming a file is compatible because it contains no obvious Node import.

Use the framework's runtime documentation and the installed library version to verify support. If the intended route needs Node, configure and test that route accordingly. Do not replace a mature storage driver with a new service solely to satisfy a mistaken runtime setting.

Also check filesystem assumptions. A temporary directory may be writable while the application bundle is read-only, and local files may not persist between instances. If an upload is meant to survive requests, use durable storage with an explicit contract. A local development write is not proof of deployment durability.

Exercise a built application in isolation

Run the production build without a development server listening. This catches pages that fetch their own local API during generation. Start the built application with the intended configuration shape, then make direct requests to the representative routes. Use a synthetic database or dedicated test records and avoid altering customer content.

A smoke check should validate more than status 200. Confirm a distinctive article sentence, title, canonical URL, and expected public fields. An HTML error page or empty shell can also arrive with a successful status. Check the API response schema when an endpoint is part of the journey.

Use a deployment-like network policy where practical. Test provider timeouts and unavailable storage with controlled failures. A passing local container does not establish that the hosting network permits the same connection; retain a bounded deployment smoke check for that real boundary.

Verify failures and recovery

Remove a required variable in the isolated environment and confirm a clear safe error. Make the database unavailable and verify that the request does not hang indefinitely or report a missing article. Restore it and check whether the process recovers without a restart. A cached rejected connection promise can make a transient outage permanent for that instance.

Test publication after deployment. An edit that reaches storage but fails to invalidate public output needs observable recovery. Request the article, index, metadata, and sitemap after a synthetic change. Content freshness describes those checks in more detail.

Avoid broad catch blocks added solely to make smoke checks green. A fallback may be an intended user experience, but the check should still distinguish fallback operation from healthy dependency operation. Otherwise monitoring says the deployment works while every user receives stale or empty content.

Use AI to compare environments safely

Provide the assistant with variable names, package versions, runtime settings, sanitized logs, and the failing route. Ask it to compare local and deployment assumptions in a table with evidence for each difference. Do not provide connection strings, tokens, or real user records.

Require proposed fixes to explain which assumption they remove. Adding retry logic does not fix an invalid secret. Switching a route to dynamic rendering does not fix an incompatible runtime import. Setting an absolute API origin may merely point a build at an older deployment. The smallest safe fix addresses the observed boundary.

Then ask for a regression check that would fail before the repair. Review whether it exercises the real problem or mocks it away. A test replacing the driver with a successful stub cannot establish deployment database connectivity. It can still verify application error handling if its scope is stated honestly.

Keep checks proportional and repeatable

A small application does not need a full copy of production for every pull request. It does need repeatable checks of its critical contracts and one bounded check of the deployed system. Use isolated fixtures, explicit timeouts, and cleanup that cannot reach production data.

Record unverified boundaries in the release evidence. If a provider check could not run because credentials were unavailable, say so rather than treating the compile as equivalent. That limitation helps the person releasing the change choose the remaining check.

Server-to-self fetch diagnosis covers one common build-only failure. Recoverable database connections covers a runtime failure that can remain after the network is restored. A useful deployment checklist connects those concrete risks to observable outcomes.