Configuration Validation

Fail at startup with a clear message instead of at 3am with a null.

moderate Developer Experience

What it adds

A startup check that every required setting is present, well-formed, and consistent — reporting all problems at once, in plain language.

What your agent is told to do

1
Declare every setting the app reads in one place: its name, whether it is required, which environments require it, its expected format, and a one-line description of what it does.
2
Validate at startup, before the app accepts traffic. Report every problem in a single pass — an operator fixing one missing variable per deploy cycle is a bad afternoon.
3
Say what is wrong and what to do. 'DATABASE_URL is missing; expected a postgres:// connection string' beats a nil error six frames deep.
4
Validate relationships as well as individual values. A setting that is required only when a feature flag is on, or a pair that must both be set or both be absent, is where the real breakage lives.
5
Fail closed in production for anything unsafe to omit, but allow sensible local defaults in development so a new contributor can boot the app.
6
Do NOT print, log, or include secret values in validation errors. Report the name, the expected shape, and whether it is present — never the value, not even truncated.
7
Classify settings as required, optional, deprecated, or environment-specific, and warn on deprecated ones with the replacement name.

Edge cases it handles

An empty string is not the same as unset, and the difference is usually a bug. Decide explicitly which one counts as missing.
Type coercion is a silent failure mode. The string 'false' is truthy in most languages, and 'no' is not a number.
Settings that point at external services should be checked for shape at startup but not necessarily connected to — a strict connectivity check turns a slow dependency into a boot failure.
Validation must run identically in every environment that boots the app, including migration containers, one-off consoles, and scheduled tasks, or a missing value surfaces only in the path nobody tested.
Deployment templates and the documented example file must be generated from the same declaration, or the list drifts within a month.
A validation failure must exit with a non-zero status and a readable message on stderr, so the deploy fails visibly rather than crash-looping quietly.
Do not require production-only settings in a test run, or the test suite becomes a place where secrets have to exist.

Definition of done

Every setting the app reads is declared in one place with its requirement level and format.
Startup validation reports all failures at once and refuses to serve traffic on failure.
Error messages name the setting, the expected shape, and the fix, and never contain the value.
Cross-setting relationships and conditionally required settings are validated.
Development boots with defaults while production fails closed on unsafe omissions.
Deprecated settings warn and name their replacement.
The documented example configuration is generated from the declaration.
The feature matches the existing design system.
No existing functionality is broken.

Related features

AI Cost Budgets

Multi-Model Routing

SEO Setup

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.