Convex Return Validators

When to and when not to use return validators in Convex

Convex recently updated its guidance on return validators. The old rule was "always add a returns validator." The new guidance is: prefer simple TypeScript types and inference by default. Use returns: when you actually want Convex to enforce an exact runtime contract.

Return validators aren't bad. The word "always" was doing damage.

What is a return validator?

Convex lets you validate arguments coming into a function using args and return values going out using returns. A return validator declares the return shape, and Convex checks it at runtime.

import { query } from "./_generated/server";
import { v } from "convex/values";

export const getUserPreview = query({
  args: { userId: v.id("users") },
  returns: v.object({
    name: v.string(),
  }),
  handler: async (ctx, { userId }) => {
    const user = await ctx.db.get(userId);
    if (!user) throw new Error("User not found");
    return { name: user.name };
  },
});

If the returned value doesn't match, you get a runtime error instead of silently returning unexpected data. Object validators don't allow extra properties — returning extra fields will fail validation at runtime.

Why the old "always" rule existed

The original motivation was more about TypeScript pain than runtime correctness. Convex projects can hit circular type problems because functions reference generated api or internal objects, and those references become part of the generated types. Types reference types reference types until TypeScript gives up.

The thinking: if the model always declared return validators, it would reduce reliance on inferred return types and break the cycle. In practice, it only helps in specific circumstances.

Why "always" causes problems

In real codebases, and especially in agentic AI workflows, the "always" rule creates predictable failure modes:

Verbosity and copy-paste fragility

LLMs don't reuse validators. They copy-paste shapes inline. You end up with return validators like this on every function:

export const listByProject = query({
  args: { projectId: v.id("projects") },
  returns: v.array(
    v.object({
      _id: v.id("activityLog"),
      _creationTime: v.number(),
      action: v.string(),
      userId: v.id("users"),
      userName: v.string(),
      projectId: v.id("projects"),
      entityType: v.string(),
      entityId: v.string(),
      metadata: v.optional(v.string()),
    }),
  ),
  handler: async (ctx, args) => {
    // ...
  },
});

It works, but once that shape is copy-pasted across multiple functions, a schema change stops being a "change one place" job. You update a field, chase compile errors, chase runtime validation errors, then update a bunch of validators that are almost-the-same-but-not-quite.

Token inefficiency for AI

Every extra hundred tokens matters when the model is trying to keep the codebase in working memory and plan multi-step changes. Verbosity translates into slower iterations and more "oops, I forgot a field" cycles.

Hallucination risk

Asking a model to reproduce a schema as a validator increases the chance it invents fields, misses fields, or picks the wrong validator type. TypeScript catches a lot of this, but catching things later is still slower than not introducing the problem.

System field duplication

Unless you're using helper utilities, return validators drag you into re-declaring _id and _creationTime over and over. If you want heavy validator usage, look at the validator utilities in convex-helpers.

Convex already provides ergonomic type helpers like Doc<> and WithoutSystemFields, so a lot of the time you can keep code tidier by leaning on normal TypeScript types and inference.

The "exact type" problem — where return validators shine

TypeScript is structurally typed, which means it doesn't have true exact types. A function can claim it returns a User but still accidentally return extra fields.

This becomes more likely once any gets involved, or when consuming untyped external API data:

// WITHOUT return validator — extra field leaks silently
export const getUser = query({
  args: {},
  handler: async (ctx): Promise<User> => {
    return {
      id: "123",
      name: "Alice",
      email: "alice@example.com", // Extra field — no error!
    } as any;
  },
});

// WITH return validator — Convex catches extra field at runtime
export const getUser = query({
  args: {},
  returns: v.object({
    id: v.string(),
    name: v.string(),
  }),
  handler: async (ctx) => {
    return {
      id: "123",
      name: "Alice",
      email: "alice@example.com", // Runtime error!
    } as any;
  },
});

That guarantee is real and valuable. It's just not needed everywhere, and using it everywhere comes with costs.

When you SHOULD use return validators

Return validators are useful when you need runtime enforcement of an exact contract, not just TypeScript typechecking.

Components codegen

There are cases where inference isn't available and the validator becomes the contract.

Static codegen workflows

With static codegen, functions don't have return type inference and will default to v.any() if they don't have a returns validator.

OpenAPI generation

You often want the server to enforce the contract you're generating client types from. Missing validators get treated as any, which makes the resulting spec less useful.