What this usually means
The satisfies operator asserts that the type of an expression matches a given type without changing the expression's inferred type. Errors typically occur because satisfies does not narrow the type in the way you expect — it validates but does not widen or narrow. Common pitfalls include treating satisfies like a type cast, forgetting that excess property checks are not enforced by satisfies in the same way as direct annotations, and assuming that satisfies works with conditional types or discriminated unions as a type guard.
The first ten minutes — establish facts before touching code.
- 1Check if you used satisfies on a value that includes optional or undefined properties — satisfies does not remove undefined from the type, it only checks compatibility.
- 2Replace satisfies with a direct type annotation (e.g., ': MyType') and see if the error changes — this isolates whether the issue is with satisfies semantics vs. type mismatch.
- 3Inspect the inferred type of the expression using hover in your editor — if the type is still wide (e.g., 'string | number' instead of a literal), satisfies didn't narrow it.
- 4Test with a simple example: declare a const with satisfies and without; compare the inferred types in a .d.ts or by hovering.
- 5Check if you have enabled exactOptionalPropertyTypes in tsconfig — this can cause excess property errors with satisfies that otherwise wouldn't appear.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchtsconfig.json (check exactOptionalPropertyTypes, strictNullChecks)
- searchThe exact line where satisfies is used — hover to see inferred type
- searchType definitions for the type you're satisfying (is it a union? does it have index signatures?)
- searchDownstream usage of the satisfied value (function calls, property accesses)
- searchConditional branches or ternary expressions using the satisfied value
- searchPrevious version of the code that used 'as const' or explicit annotation for comparison
Practical causes, not theory. These are the things you will actually find.
- warningTreating satisfies as a narrowing operator — it doesn't narrow unions, it only validates compatibility.
- warningExcess property checks are not performed by satisfies; a value can satisfy a type even if it has extra properties that the type doesn't mention.
- warningUsing satisfies with optional properties: the property may still be undefined after satisfies, leading to 'undefined' errors downstream.
- warningMisunderstanding that satisfies does not change the literal type to the target type; the expression keeps its original literal type.
- warningInterference from exactOptionalPropertyTypes causing unexpected errors with satisfies and object literals.
Concrete fix directions. Pick the one that matches your root cause.
- buildIf you need narrowing, use a type guard or conditional check after satisfies, or use an 'as' assertion with caution.
- buildTo enforce excess property checks, use a direct type annotation on the variable instead of satisfies, or pass the value to a function that expects the type.
- buildFor optional properties, use the non-null assertion (!) after satisfies only if you're certain, or provide a default value.
- buildTo get a narrowed literal type, combine satisfies with 'as const' on the value, e.g., 'const x = { ... } as const satisfies SomeType'.
- buildWhen using satisfies with arrays, explicitly type the array element if you need the array type to be narrower, e.g., 'const arr = [1, 'a'] as const satisfies readonly (string | number)[]'.
A fix you cannot prove is a guess. Close the loop.
- verifiedHover over the variable after the fix to ensure the inferred type matches expectations (e.g., property values are literals, not unions).
- verifiedCompile with --noEmit and verify zero errors, especially with strictNullChecks enabled.
- verifiedWrite a small test that accesses the value in a way that would fail if the type is too wide (e.g., pass to a function expecting a specific literal).
- verifiedCheck autocomplete suggestions in an editor to ensure only valid properties appear.
- verifiedRun TypeScript's built-in type checking on the entire project to catch any cascading type errors.
Things that make this bug worse or harder to find.
- warningUsing satisfies as a substitute for runtime validation — it is a compile-time only check.
- warningOverusing satisfies on every variable when a simple type annotation would be clearer and safer.
- warningAssuming satisfies will catch all type errors; it only checks compatibility, not exactness.
- warningCombining satisfies with complex conditional types without testing the inferred type first.
- warningIgnoring the 'as const' combination when you need both literal inference and type validation.
The Satisfied But Still Undefined Nightmare
Timeline
- 09:15Pushed a PR refactoring config objects from 'as const' to satisfies for better validation.
- 09:45CI fails with type errors: 'Property 'color' does not exist on type ...' in a downstream component.
- 10:00Hover over the config variable: type shows all properties as optional, even though they were required in the object literal.
- 10:20Check tsconfig: exactOptionalPropertyTypes is true. This causes satisfies to treat missing optional properties as errors? No, actually it causes excess property checks on object literals assigned to types with optional properties.
- 10:35Realize that satisfies does not enforce excess property checks, but the downstream component expects the exact type without extra properties.
- 10:50Change satisfies to a direct type annotation on the variable, fixing the excess property issue.
- 11:00But now the type is widened to the interface, losing literal values. Need to incorporate 'as const' back.
- 11:15Final fix: 'const config = { ... } as const satisfies Config;' — this preserves literal types and validates structure.
I was migrating a large configuration object from 'as const' to the new satisfies operator, thinking it would give me the best of both worlds: literal inference and type validation. The object had about 20 properties, some optional, and was used across multiple components. After the change, CI failed with a cascade of type errors in components that were accessing properties that TypeScript now considered possibly undefined.
The first clue was that hovering over the config variable showed all properties as optional, even though I had supplied every required property in the literal. It turns out that with exactOptionalPropertyTypes enabled, satisfies treats an object literal as having all properties optional if the target type has optional properties, because the excess property check is not performed. The downstream components were expecting a type where those properties were required, so they got errors.
I reverted to a direct type annotation on the variable, which fixed the excess property issue but widened the types, breaking literal inference. The real fix was to combine 'as const' with satisfies: 'as const satisfies Config'. This preserves the literal types and validates the shape. The lesson: satisfies is not a drop-in replacement for 'as const' — you need to understand its interaction with optional properties and strict settings.
Root cause
exactOptionalPropertyTypes in tsconfig caused satisfies to not enforce required properties on object literals, making properties appear optional.
The fix
Changed from 'satisfies Config' to 'as const satisfies Config' to preserve literal inference and ensure properties are required.
The lesson
Always check tsconfig strict settings when using satisfies, and combine with 'as const' when you need both literal inference and validation.
The satisfies operator validates that an expression's type is assignable to the target type, but it does not change the expression's type. In contrast, a type annotation like ': MyType' widens the expression to that type, potentially losing literal information. 'as const' makes the type deeply readonly and narrows all values to literals, but does not validate against a target type.
For example: 'const x = { a: 'hello' } satisfies { a: string }' — x's type is '{ a: string }'? No, it's actually '{ a: "hello" }'. The satisfies checks that the literal type is assignable to '{ a: string }', but x remains the literal type. This is great for preserving narrow types, but can be surprising if you expect the type to be the target type.
TypeScript performs excess property checks on object literals when they are assigned to a type with a direct annotation or passed as an argument. However, satisfies does NOT trigger excess property checks. This means you can have extra properties in the literal that are not in the target type, and satisfies will still pass.
This can lead to runtime errors if you later use the value in a context that expects the exact target type. To enforce excess property checks, you need to either use a direct type annotation or pass the value to a function that expects the type. Alternatively, you can use a helper type like 'Exactify' but that's complex.
When a target type has optional properties, satisfies does not require those properties to be present. But if you use exactOptionalPropertyTypes, the behavior changes: a property that is optional in the target type but missing in the literal will cause an error, because the literal's type doesn't have that property at all (not even as undefined).
I've seen teams spend hours debugging why satisfies fails on an object that clearly matches the type. The fix is to either disable exactOptionalPropertyTypes, add the missing optional property with a value of undefined, or use a union type that explicitly includes undefined.
A common use case is using satisfies to validate that an object literal matches one branch of a discriminated union. For example: 'const event = { type: 'click', x: 10, y: 20 } satisfies ClickEvent | DragEvent'. This works, but the inferred type of 'event' is still the literal type, not the union. This means you can access 'type' but not 'x' or 'y' without a type guard.
If you need the discriminated union type for narrowing, you should use a type annotation instead of satisfies. Alternatively, you can use satisfies and then narrow with a type guard on the discriminant property.
Step 1: Check the inferred type by hovering over the variable. If it's a literal, satisfies is working; if it's the target type, you might have a type annotation elsewhere. Step 2: Temporarily replace satisfies with a direct annotation to see if the error changes. If it does, the issue is likely excess property checks or widening. Step 3: Check tsconfig for exactOptionalPropertyTypes and strictNullChecks. Step 4: If using with arrays, ensure you use 'as const' if you need literal elements.
Another technique: extract the expression to a separate variable and see if the error persists. This helps isolate whether the issue is with satisfies or the context where the variable is used.
Frequently asked questions
Does satisfies perform excess property checks?
No, satisfies does not perform excess property checks on object literals. It only checks that the expression's type is assignable to the target type. Extra properties in the literal are allowed. To enforce excess property checks, use a direct type annotation instead.
Why does satisfies not narrow the type like a type guard?
satisfies is not a type guard; it is a validation operator. It checks that an expression's type is assignable to the target type, but it does not change the expression's type. The expression keeps its original inferred type. If you need narrowing, you must use a type guard (e.g., 'if (typeof x === 'string')') or an 'as' assertion.
Can I use satisfies with 'as const' together?
Yes, you can combine 'as const' and satisfies: 'const x = { ... } as const satisfies SomeType'. This gives you both literal inference (from 'as const') and validation against the target type (from satisfies). The 'as const' must come before satisfies.
What does exactOptionalPropertyTypes do with satisfies?
When exactOptionalPropertyTypes is enabled, TypeScript requires that optional properties be explicitly set to undefined if they are omitted, rather than just missing. With satisfies, this can cause errors if an optional property is missing from the literal, because the literal's type doesn't have that property at all. The fix is either to disable the option, add the property with undefined, or use a different approach.
How do I debug a satisfies error that says 'Type X does not satisfy the constraint'?
This error means the expression's type is not assignable to the target type. Hover over the expression to see its inferred type, then compare it to the target type. Look for differences in property types, optionality, or union members. Use a tool like 'Extract' or 'Exclude' to isolate the mismatch. Also check if the target type is a union and the expression matches more than one branch ambiguously.