STITCH_DRIFT

What you will see

A call fails during validation with a drift finding that carries level: 'error' and change: 'invalid'. The finding names the offending path and the call surfaces a StitchError with code STITCH_DRIFT instead of a result.

Why it happens

Drift validates the live response against the declared output schema (the consumer contract). A required field was missing or the value was incompatible with its declared type — the schema could not produce a valid result. Because the field is required, this is a hard contract break: the engine throws rather than returning a value that does not match the declared TypeScript type.

Soft drift (undeclared, coerced, defaulted) is always non-fatal. Fatality lives entirely in the schema: a required field whose absence or type mismatch throws; an optional field whose absence is silently tolerated.

How to fix

Read the finding's path to see exactly what moved, then decide which case you are in:

• The change is intended. The upstream shape genuinely changed and you want the new shape. Update the output schema to match the new type or mark the field optional, and the error stops.
• It is a vendor regression. You did not expect this change — that is the signal drift exists to give you. Treat the thrown error as the alert and act on the upstream break.

If a field should be tolerated when absent, declare it .optional() in the schema. Validation will then succeed, and drift may emit a soft defaulted finding if the schema has a .default() — but the call will not throw.

import { drift, stitch } from 'stitchapi';
import { z } from 'zod';

const user = stitch({
    baseUrl: 'https://api.example.com',
    path: '/user',
    output: drift(
        z.object({
            // `id` is required — its absence or type mismatch throws STITCH_DRIFT.
            id: z.number(),
            // `displayName` is optional — its absence is tolerated, no error thrown.
            displayName: z.string().optional(),
        }),
    ),
});

See the drift guide for how the schema's required/optional structure maps to finding levels, and how severity and ignore filter soft findings.

Related