Two things slipped through:

  1. The an ecommerce business — a prior replacement left a broken article ("The an"). Fixing to read naturally.
  2. the Utopia dashboard — internal project codename; replacing with what it is ("an internal dashboard").

Everything else checks out: Recharge is a public SaaS platform (keep), all tech names are public, no dollar figures, no people's names.

TLDR: Requiring env vars at startup is good. Requiring every var in one shared list that every route calls is a trap — one missing secret nukes your entire backend at once.

The Setup

An ecommerce business's supply chain syncs run on Vercel cron routes — Shopify orders, inventory, Recharge (our subscriptions platform) subscriptions, snapshots, the works.

We did the right thing early: no silent || undefined fallbacks. If a required server var is missing, we blow up loud.

Felt great.

What "Failing Loud" Actually Looked Like on May 26th

Data froze.

Not one feature — everything. Orders not syncing. Inventory stale. Recharge data missing. Snapshots gone dark.

First instinct: Vercel scheduler. Maybe jobs weren't firing?

Scheduler was fine. Jobs were firing, getting HTTP 500s back in ~0.4 seconds, and quietly moving on.

The actual error: {"error":"Missing required server environment variable: RECHARGE_ACCESS_TOKEN"}.

The Root Cause (and It's a Pattern)

Here's what was happening in src/lib/env.ts:

requiredServerEnvVars = ['CRON_SECRET', 'SUPABASE_SERVICE_ROLE_KEY', 'RECHARGE_ACCESS_TOKEN']

Every route — /api/shopify-orders-sync, /api/shopify-inventory-sync, /api/inventory-snapshot, ALL of them — called assertServerEnv() at request time.

assertServerEnv() throws if any var in that list is missing.

The Recharge integration shipped around May 26th and added RECHARGE_ACCESS_TOKEN to the required list. The token never got set in the production Vercel environment.

So: one missing var for one feature → every single cron route 500s before doing any work.

Orders doesn't need RECHARGE_ACCESS_TOKEN. Inventory doesn't need it. Snapshot definitely doesn't need it.

Didn't matter. They all checked. They all died.

The Fix (Honest Version)

We set the missing var in Vercel and everything came back.

That's it. That was the immediate fix.

The real fix — making each route assert only the vars it actually uses — is the lesson I'm now actively applying. I did it for an internal dashboard last week: require the env vars, but only the ones that route actually touches. Removed every hardcoded fallback. Tightened the blast radius.

It's what I should've done from the start.

Why This Matters to Me

I was proud of that assertServerEnv() pattern. Fail loud — yes! No silent degradation! We're being responsible builders!

And then it nuked four independent cron jobs simultaneously over one missing key in a platform we'd just started integrating.

The lesson isn't "require your env vars." That part was right.

The lesson is fail NARROW. Each service, each route, each worker should check exactly what it needs — nothing more. Because when you couple every requirement into a shared list, you're not building a safety net. You're building a breaker that trips the whole panel.

Blast radius matters as much as fail-loudness.