Fix: TypeScript Generic Type Constraint Errors

The Error

You write a generic TypeScript function or class and get:

Type 'string' does not satisfy the constraint 'number'.

Or:

Type 'X' does not satisfy the constraint 'Y'.
  Type 'string' is not assignable to type 'number'.

Or:

Argument of type 'string' is not assignable to parameter of type 'T extends object'.

Or TypeScript infers unknown or {} when you expected a more specific type:

Type 'unknown' is not assignable to type 'string'.

Why This Happens

TypeScript generics use the extends keyword to add constraints — the generic type parameter must be assignable to the constraint type. Errors occur when:

• The passed type does not satisfy the constraint — e.g., passing string where T extends object is required.
• TypeScript cannot infer the generic type and falls back to unknown or {}.
• The constraint is too narrow — requires a specific structure that the type does not have.
• The constraint is too wide — T extends object allows null in some versions or unexpected types.
• Conditional types resolve incorrectly — T extends X ? A : B behaves unexpectedly with union types.

Generic constraints in TypeScript are an assignability check, not a nominal class check. The compiler asks “can a value of T be safely used where the constraint type is expected?” using structural typing. Two unrelated classes with the same shape both satisfy T extends { name: string }. That structural rule is also why most “does not satisfy” errors look subtle — the message reports the first missing or incompatible property along the assignability chain, not the highest-level mismatch you might have spotted by eye.

A second source of confusion is the difference between the constraint of a parameter and the type that the parameter ends up bound to. The constraint defines what the caller is allowed to pass; the bound type is what TypeScript actually uses inside the function body. Inside the function, T is treated as the constraint type unless the function returns or stores T in a way that forces a more specific inference. This is why returning T is far stricter than accepting T and returning the constraint — and why mapping over keys with K extends keyof T works for both reads and writes, while a plain K does not.

Platform and Environment Differences

TypeScript’s generic constraint rules have evolved meaningfully across versions, and the surrounding toolchain (Flow, Sorbet, JSDoc, satisfies, const generics) affects what you can express and how errors are presented:

• TS strict mode vs JSDoc-only checking. Pure JavaScript projects can opt into type checking via // @ts-check and JSDoc generics (@template T, @param {T}). JSDoc generics work but the diagnostic messages are softer and inference is less aggressive than in .ts files. Mixed codebases where some files are .js with JSDoc and others are .ts see different error wording for the same logical mistake. Turning on strict: true in tsconfig.json tightens null handling and forces explicit any — many constraint errors only surface under strict mode.
• TypeScript vs Flow vs Sorbet philosophy. Flow uses bounded polymorphism with T: Constraint syntax and a different variance model; Sorbet (Ruby) uses runtime sigs with T.type_parameter. Code-translation between them is mechanical at the shape level but the inference quality differs. TypeScript’s bivariance for function parameters (relaxed by strictFunctionTypes) means a constraint that works in TypeScript can be tighter in Flow.
• Narrowing in conditional types. Conditional types (T extends X ? A : B) distribute over naked union type parameters. Wrap the type parameter in a tuple ([T] extends [X]) to suppress distribution. This trick is universal across TS versions, but recursive conditional types only work cleanly from 4.1, when tail-recursion elimination was introduced.
• The satisfies operator (4.9+). satisfies checks a value against a type without widening it, so you can keep literal types while validating shape. Before 4.9 the only options were a type assertion (loses safety) or a typed const (widens). If your codebase targets a compiler older than 4.9, the satisfies pattern is unavailable and you fall back to helper functions like function asConst<T extends X>(v: T): T { return v; }.
• const type parameters (5.0+). A const modifier on a type parameter (function f<const T>(x: T)) tells the compiler to infer literal types for x. Before 5.0 you needed as const at the call site, which leaks into the value type. Library APIs designed before 5.0 often expose as const patterns in their docs; modern APIs can use const T to remove that ceremony.
• Inferred type predicates (5.5+). From 5.5, TypeScript can infer that a function like (x: T) => boolean actually narrows x to a subtype, eliminating the need to write x is Subtype manually for many cases. This affects how generic filter helpers narrow inside Array.prototype.filter and similar APIs.
• Module resolution and target flags. moduleResolution: bundler (5.0+) changes how .d.ts files are resolved, which can change which overload of a generic function is picked up. strictFunctionTypes flips parameter variance; noUncheckedIndexedAccess adds undefined to indexed reads, changing whether T[K] is T[K] or T[K] | undefined. Constraint errors that only appear on one developer’s machine often trace back to differing tsconfig.json strict flags.

Fix 1: Understand extends in Generic Constraints

extends in a generic constraint means “is assignable to” — not class inheritance:

// T must be assignable to string (only string and string literal types)
function echo<T extends string>(value: T): T {
  return value;
}

echo("hello");     // OK — string satisfies string
echo(42);          // Error — number does not satisfy string
echo(true);        // Error — boolean does not satisfy string

// T must be an object with a name property
function greet<T extends { name: string }>(obj: T): string {
  return `Hello, ${obj.name}`;
}

greet({ name: "Alice", age: 30 }); // OK — has name: string
greet({ age: 30 });                 // Error — missing name property
greet("Alice");                     // Error — string is not an object

The constraint defines the minimum requirements for T. Any type that satisfies those requirements is accepted.

Fix 2: Fix “Type Does Not Satisfy the Constraint”

The passed type is missing required properties or is the wrong kind:

Broken — passing wrong type:

function getProperty<T extends object, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

getProperty("hello", "length"); // Error: string does not satisfy constraint 'object'
// string is a primitive, not an object

Fixed — pass an object:

getProperty({ name: "Alice" }, "name"); // OK

// If you need to support strings, widen the constraint:
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

getProperty("hello", "length"); // Now OK — T inferred as string

Common constraint patterns and their meanings:

// T must be an object (not primitive)
function process<T extends object>(value: T): T { ... }

// T must be a string or number
function compare<T extends string | number>(a: T, b: T): boolean { ... }

// T must have specific properties
function serialize<T extends { id: number; toJSON(): string }>(item: T): string {
  return item.toJSON();
}

// T must be a constructor function
function createInstance<T>(ctor: new () => T): T {
  return new ctor();
}

// T must be a key of another type
function pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
  const result = {} as Pick<T, K>;
  keys.forEach(key => result[key] = obj[key]);
  return result;
}

Fix 3: Fix Generic Inference Failures

TypeScript sometimes infers unknown or {} when it cannot determine the generic type:

Broken — inference fails:

function identity<T>(value: T): T {
  return value;
}

const result = identity([]); // T inferred as never[] — empty array
result.push("string");        // Error: Argument of type 'string' is not assignable to 'never'

Fixed — provide explicit type argument:

const result = identity<string[]>([]); // T explicitly set to string[]
result.push("string"); // OK

Broken — inference across function calls:

async function fetchData<T>(): Promise<T> {
  const response = await fetch("/api/data");
  return response.json(); // Returns Promise<any> — T is not connected
}

const data = await fetchData(); // T inferred as unknown
data.name;                      // Error: 'data' is of type 'unknown'

Fixed — provide type argument:

interface User { name: string; email: string; }

const data = await fetchData<User>(); // Explicitly specify T
data.name; // OK — TypeScript knows it's a User

Pro Tip: When TypeScript infers a generic type as unknown or {}, it means the inference engine does not have enough information. This is usually a signal to either provide an explicit type argument or restructure the function to give TypeScript more context.

Fix 4: Fix Constraints with Multiple Type Parameters

When multiple type parameters interact, constraints can become complex:

Broken — K not constrained to T’s keys:

function mapValues<T, K, V>(obj: T, key: K, value: V) {
  obj[key] = value; // Error — K is not constrained to keyof T
}

Fixed — constrain K to keyof T:

function mapValues<T extends object, K extends keyof T>(
  obj: T,
  key: K,
  value: T[K]  // Value must match the type of obj[key]
): T {
  obj[key] = value;
  return obj;
}

const user = { name: "Alice", age: 30 };
mapValues(user, "name", "Bob");    // OK
mapValues(user, "age", 31);        // OK
mapValues(user, "name", 42);       // Error — number not assignable to string
mapValues(user, "email", "[email protected]"); // Error — 'email' not a key of user

Fix 5: Fix Conditional Type Behavior with Unions

Conditional types (T extends X ? A : B) distribute over union types by default, which can produce unexpected results:

Unexpected distribution:

type IsString<T> = T extends string ? true : false;

type A = IsString<string>;          // true
type B = IsString<number>;          // false
type C = IsString<string | number>; // boolean (true | false) — distributes over union!

IsString<string | number> distributes to IsString<string> | IsString<number> = true | false = boolean.

Prevent distribution by wrapping in a tuple:

type IsString<T> = [T] extends [string] ? true : false;

type C = IsString<string | number>; // false — [string | number] extends [string]? No.
type D = IsString<string>;          // true

Use distributed conditional types intentionally:

// Extract only string types from a union
type OnlyStrings<T> = T extends string ? T : never;

type Result = OnlyStrings<string | number | boolean>; // string

Fix 6: Fix extends with Interfaces and Classes

extends in generics works with interfaces and classes based on structural typing — TypeScript checks shape, not identity:

interface Serializable {
  serialize(): string;
}

class User implements Serializable {
  constructor(public name: string) {}
  serialize() { return JSON.stringify({ name: this.name }); }
}

class Config {
  constructor(public key: string, public value: string) {}
  serialize() { return `${this.key}=${this.value}`; }
  // No 'implements Serializable' — but structurally compatible
}

function save<T extends Serializable>(item: T): string {
  return item.serialize();
}

save(new User("Alice")); // OK — User implements Serializable
save(new Config("a", "b")); // OK — Config is structurally compatible
save({ serialize: () => "data" }); // OK — inline object is compatible
save("string"); // Error — string does not have serialize()

Constraint error with this type:

class Builder<T extends Builder<T>> {
  build(): T {
    return this as unknown as T; // Requires cast
  }
}

class UserBuilder extends Builder<UserBuilder> {
  setName(name: string): this { // 'this' type narrows correctly
    return this;
  }
}

Fix 7: Fix “Type Instantiation Is Excessively Deep”

Complex nested generics can hit TypeScript’s recursion limit:

Type instantiation is excessively deep and possibly infinite.

Simplify recursive types with a depth limit:

// Broken — infinitely recursive
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

// Fixed — limit recursion depth
type DeepReadonly<T, Depth extends number = 5> =
  Depth extends 0
    ? T
    : { readonly [K in keyof T]: T[K] extends object
        ? DeepReadonly<T[K], [-1, 0, 1, 2, 3, 4][Depth]>
        : T[K] };

Or use a library like type-fest which provides battle-tested deep utility types:

npm install type-fest

import type { ReadonlyDeep } from "type-fest";

type Config = ReadonlyDeep<{
  database: { host: string; port: number };
  cache: { ttl: number };
}>;

Common Generic Constraint Patterns

// Ensure T is not null or undefined
function nonNull<T extends NonNullable<T>>(value: T): T { ... }

// Ensure T is a class constructor
function mixins<T extends new (...args: any[]) => {}>(Base: T) { ... }

// Ensure T has a length property
function first<T extends { length: number; [index: number]: any }>(arr: T): T[0] {
  return arr[0];
}

// Ensure T is a Promise
function unwrap<T extends Promise<unknown>>(promise: T): Awaited<T> { ... }

// Constrain to specific record shapes
function merge<T extends Record<string, unknown>>(a: T, b: Partial<T>): T {
  return { ...a, ...b };
}

Still Not Working?

Use satisfies operator (TypeScript 4.9+) to validate a value against a type without widening it:

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
} satisfies Record<string, string | number[]>;

// palette.red is still number[], not string | number[]
// satisfies checks the shape but preserves the literal type

Use infer in conditional types to extract types within constraints:

type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

type Fn = (x: number) => string;
type Result = ReturnType<Fn>; // string

Enable strict mode for better generic error messages — "strict": true in tsconfig.json catches more type errors earlier.

Verify your TypeScript version matches the feature you are using. satisfies, const type parameters, recursive conditional types, and inferred type predicates each have a hard minimum version. Run npx tsc --version and compare against the feature you expect — a constraint error that “should not happen” often means the compiler is older than you think because a workspace pinned typescript to an old release.

Inspect inferred types with the language server. Hover over the call site in VS Code to see what TypeScript actually inferred for each type parameter. If you see unknown, the compiler decided it could not infer; if you see a literal like "Alice" where you expected string, a const T or as const is in play. The hover view is faster than guessing.

Reduce noise from any. A single any in the type graph can defeat constraint checks downstream. Enable noImplicitAny and strict, then chase any back to its source. The constraint error you fix may move, but the type model becomes coherent again.

For related TypeScript errors, see Fix: TypeScript Type Not Assignable and Fix: TypeScript Object is Possibly Undefined. For conditional type problems, see Fix: TypeScript Conditional Types Not Working. For discriminated union narrowing, see Fix: TypeScript Discriminated Union Error.