Server Component Crash Behind a 200 OK Response

Conclusion

A 200 status and a successful JSON parse don’t guarantee the response shape matches the contract. (await res.json()) as T only tells the compiler what to believe — it checks nothing at runtime. Pass a 200 response missing a required field straight downstream, and a React Server Component built on that assumption crashes.

Symptom

kimiteras-portal has a function, fetchV2Metrics (src/lib/v2-metrics.ts), that pulls monthly effectiveness metrics — impressions, taps, dwell seconds — from a v2 API. The top of that file spells out an explicit invariant in a comment:

Fallback contract: on any failure whatsoever (unconfigured, unlinked, 401/404/422/5xx,
network error), never throw — return { ok:false, reason, status? }. The caller (the
report screen) falls back safely to manual ad_metrics or an "unlinked" state.

The implementation matched that contract for network errors, JSON parse errors, 401/404, and other HTTP errors — each returned { ok: false, reason } via try/catch and branching, as promised.

Except the one path where res.ok was true and the JSON parsed cleanly returned { ok: true, data } with zero validation of what was actually inside:

if (res.ok) {
  try {
    const data = (await res.json()) as V2Metrics;
    return { ok: true, data };
  } catch (e) {
    return {
      ok: false,
      reason: `parse_error: ${e instanceof Error ? e.message : String(e)}`,
    };
  }
}

The caller, V2MetricsPanel (a Server Component), pulls totals out of that data and reads impressions and dwell_seconds off it directly to render the screen:

export default function V2MetricsPanel({ data }: { data: V2Metrics }) {
  const t = data.totals;
  const isLive = data.source === "live";

  const secondary = [
    { label: "Impressions", value: num(t.impressions) },
    { label: "QR / link taps", value: num(t.taps) },
    { label: "Dwell (total)", value: formatDwell(t.dwell_seconds) },
    { label: "Questions", value: num(t.asks) },
  ];

If the v2 API returned a 200 without a totals field, data.totals would be undefined, and t.impressions would throw — crashing the whole component. This was caught in code review before it ever reached a real user’s screen.

Cause

The V2Metrics type declares totals as required, not optional:

export type V2Metrics = {
  advertiser_id: string;
  company_name: string;
  period: string; // "YYYY-MM"
  tz: string;
  totals: V2MetricsTotals;
  by_school?: V2MetricsSchoolRow[];
  contracts?: V2MetricsContract[];
  generated_at: string;
  source: "monthly_reports" | "live" | string; // finalized | live
};

But fetchV2Metrics handed the JSON straight through with (await res.json()) as V2Metrics. as is a statement to the compiler, not a runtime check. When the v2 API actually returned a 200 without totals, TypeScript had no way to catch it at compile time — data passed on to the caller still carrying the type “this is a V2Metrics,” whether it actually was one or not.

In other words: the function’s own header comment promised “never throw on any failure,” and the one path exempt from that promise was the one path that looked most trustworthy — the 200. Network errors and parse errors were both guarded by try/catch, while “200, but the JSON shape doesn’t match the contract” — contract drift — sat completely unguarded.

The fix

A shape check on totals was added to the path where res.ok is true and the JSON parses cleanly:

if (res.ok) {
  let data: V2Metrics;
  try {
    data = (await res.json()) as V2Metrics;
  } catch (e) {
    return {
      ok: false,
      reason: `parse_error: ${e instanceof Error ? e.message : String(e)}`,
    };
  }
  // A 200 with an out-of-contract shape (missing totals) still falls back
  // instead of crashing V2MetricsPanel, which reads totals directly. This
  // covers the "never throw" contract across every 200 path, not just some.
  if (!data || typeof data.totals !== "object" || data.totals === null) {
    return { ok: false, reason: "parse_error: missing totals" };
  }
  return { ok: true, data };
}

If data.totals isn’t an object, or is null, the response is no longer treated as a success — it returns { ok: false, reason: "parse_error: missing totals" } and falls back instead. That stops “a 200 means the shape matches” from being something only a type assertion promises, and makes it something checked at runtime too. The caller falls back to the manual ad_metrics display, the same as any other failure mode.

Preventing a repeat

The fix didn’t stop at the guard — it added a test simulating a 200 response missing totals, to lock the regression in place:

it("200 but out-of-contract shape (missing totals) -> parse_error (falls back instead of crashing)", async () => {
  vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
    jsonResponse({ advertiser_id: ADV, period: YM }) // no totals
  );
  const r = await fetchV2Metrics(ADV, YM);
  expect(r.ok).toBe(false);
  if (r.ok) throw new Error();
  expect(r.reason).toMatch(/missing totals/);
});

Anywhere else a codebase accepts an external API’s response with nothing but as T, the same gap can exist. Any path that treats HTTP status and res.ok as proof of safety, without validating the actual shape of the payload, is worth a second look.