Runtime Type Mismatch during Router Schema Rollback

To prevent client-side crashes during a tRPC schema rollback, you must adopt additive-only schema evolution and implement runtime-aware versioning. Since tRPC relies on TypeScript's build-time type inference, it cannot natively detect when a client is expecting a structure that the server no longer provides.

Strategy for Backward Compatibility

The most effective way to handle rollbacks is to ensure the server always remains compatible with the N-1 client version. Follow these steps:

• Avoid Breaking Changes: Never rename or delete fields in your schema. If a change is required, add the new field and deprecate the old one until all clients have migrated.
• Optionality: Use Zod .optional() for new fields. This ensures that if a server rollback removes a field, the newer client-side logic handles undefined gracefully rather than crashing on a missing property.
• Server-Side Validation: Use Zod schemas to validate the output of your procedures. While tRPC infers the type, explicit validation on the server ensures the data conforms to the expected contract before it reaches the wire.

Detecting Outdated Clients

Since tRPC does not provide native version negotiation, you must implement it manually using middleware. This allows the server to detect the client's schema version before executing procedure logic.

Implementation: Version Middleware

You can pass a version identifier or a schema hash from the client via headers. The server then uses a middleware to intercept the request:

const versionMiddleware = trpc.middleware(({ next, ctx }) => {
  const clientVersion = ctx.req.headers.('x-client-schema-version');
  const minSupportedVersion = '1.2.0';

  if (clientVersion && clientVersion < minSupportedVersion) {
    throw new TRPCPCError({
      code: 'BAD_REQUEST',
n      message: 'Your client version is outdated. Please refresh the application.',
    });
  }

  return next();
});

Assumptions and Limitations

This approach assumes you have a CI/CD pipeline capable of injecting a version string into the client build metadata. Note that this does not fix the type mismatch; it simply allows the server to fail gracefully with a controlled error message rather than allowing the client to crash when attempting to parse malformed response data.