markdown-site: Skill for Cursor

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: