debug typescript types

a procedural way to debug typescript type errors that does not devolve into adding as any. follow the inference chain to the root, isolate, then fix at the root with the most specific type that satisfies both the constraint and the actual runtime value.

intent

most type errors are not where they appear, they are upstream. the error at line 47 says "string is not assignable to number", but the actual problem is a generic that got inferred too wide three layers up. the goal is to find the upstream source, fix it once, and let the rest of the inference resolve. use this skill when a user pastes a typescript type error, asks why typescript thinks X is Y, or is stuck in a cycle of narrowing assertions instead of fixing the root cause.

inputs

• the full error message (typescript's errors are noisy but every clause matters)
• the file plus line where it surfaced
• whether the code is yours, a dependency's types, or a generated declaration
• access to a typescript-aware editor (vscode with typescript support, or the typescript playground at typescriptlang.org/play)
• tsconfig.json context (especially strict mode, noImplicitAny, exactOptionalPropertyTypes settings)
• if the issue involves external types: node_modules access or package source, or knowledge of which package version is in use

procedure

step 1: read the error literally

typescript errors are precise. read every clause, not just the first sentence.

inputs: the full error message from tsc or your editor.

process:

• "type 'X' is not assignable to type 'Y'": the right-hand-side type does not satisfy the left-hand-side constraint. the constraint won, not the runtime value.
• "property 'foo' does not exist on type 'X'": the type narrowing dropped 'foo' somewhere, or the type was never union-shaped to include 'foo'.
• "type 'X | Y' is not assignable to type 'X'": something widened a union back open after a prior narrowing.
• "argument of type 'X' is not assignable to parameter of type 'Y'": the function signature expects Y but got X.

write down the actual reported type versus the actual expected type. do not skim. every word in the error is a clue.

outputs: a written statement of what the error says, not what you think it means.

step 2: find the root expression

hover the expression in your editor (vscode: hold shift and click, or use the hover tooltip) or use the assertion form // $ExpectType <Type> to query typescript directly. walk back upstream from the error site.

inputs: the file, the line where the error surfaced, an editor with typescript language support.

process:

• at each upstream expression, check the inferred type against what you expect.
• is the type correct at this point? if yes, the problem is downstream. keep moving downstream toward the error.
• is the type wrong at this point? the problem is here or further upstream. keep moving upstream.
• stop when you hit the first place where the type diverged from what you expected. that is the root.

outputs: the line number and expression where the type first went wrong.

step 3: isolate with a minimal repro

if the root is not obvious, paste the bad expression and its dependencies into a fresh .ts file or the typescript playground (typescriptlang.org/play). strip everything that does not contribute to the error.

inputs: the code context around the root expression, tsconfig settings if unusual.

process:

• delete imports, comments, and logic that do not change the error.
• if the error reproduces on 10 lines, the cause is in those 10 lines.
• if deleting a line makes the error vanish, that line is part of the cause.
• commit the minimal repro so you have a stable thing to test fixes against.

outputs: a typescript playground link or a standalone .ts file that reproduces the error with minimal code.

step 4: classify the root cause

most type errors fall into one of these buckets.

inputs: the minimal repro, the type that was inferred versus the type that was expected.

process: pick the category that matches.

• wrong generic inference: a generic got inferred to a wider type than you wanted. example: fn(x) infers T to string | number when you meant string. fix: pass the type argument explicitly, fn<string>(x).
• lost narrowing: a control-flow narrowing got dropped (assignment to a closure variable, await re-widening, conditional that widens in the else branch). example: if (x instanceof MyClass) { fn(x); } but fn does not see x as MyClass. fix: re-narrow with a type guard, or use a const local scoped to the narrow branch.
• misaligned declaration: a .d.ts says one thing but the runtime returns another. example: a third-party package declares a function returns string but it returns string | null. fix: update the types (file an issue or local override) and add a runtime check.
• structural mismatch: two types look the same but one has an extra readonly, optional, or method signature. example: { x: number; y: number } versus { readonly x: number; y: number } do not match without assertion. fix: make them genuinely compatible, do not assert through the mismatch.
• any leakage: somewhere upstream is any, polluting downstream inference. example: a function parameter is any, so its return type is any, so all assignments from it are any. fix: find the any source, give it a real type. unknown is almost always the right intermediate.

outputs: a diagnosis of which category this is, plus a hypothesis of where in the call stack the problem originated.

step 5: fix at the root with the narrowest correct type

apply the fix at the root, not at the symptom. prefer these options in order.

inputs: the root expression, the diagnosis from step 4, the tsconfig strict mode setting.

process:

1. fix the declaration if it was wrong (most durable): update the .d.ts, the function signature, or the type alias. this fixes the error at the source and prevents future mismatches. if it is a third-party package, file a PR to definitelytyped or the package upstream.
2. pass an explicit generic argument: change fn(x) to fn<MyType>(x). this prevents typescript from inferring too wide.
3. add a type guard or assertion function: create a function that returns x is NarrowType and call it in a conditional. this narrows the type in the subsequent block without losing runtime safety.
4. use satisfies (preserves inference): const x = expr satisfies MyType checks that expr conforms to MyType without widening x's inferred type. modern typescript, very useful.
5. use as <SpecificType> (only if runtime invariant is real and provable): expr as SpecificType asserts the type without a runtime check. only do this if you can prove at runtime that the expression is definitely SpecificType. add a comment explaining the runtime invariant.
6. last resort: as any then narrow immediately: never leave as any in committed code. if you must use it, follow it immediately with a narrow, add a TODO comment, and file a follow-up task.

outputs: code at the root expression that resolves the inferred type mismatch.

step 6: verify the original error is gone and no new ones appeared

re-run tsc --noEmit or your build.

inputs: the fixed code.

process:

• the original error should be gone.
• if new errors appeared, the fix moved the problem rather than solving it. go back to step 2 with the new error.
• if there are no errors, run your test suite if you have one. type correctness is not a substitute for runtime correctness.

outputs: a clean tsc exit code (0), or a list of any new errors that appeared.

decision points

• the type comes from a third-party package and the .d.ts is wrong: short-term, use module augmentation or a local declaration override (.d.ts file in your project that re-declares the type). long-term, file a PR to definitelytyped or the package maintainer. do not leave module augmentation in production code without a comment linking to the upstream issue.
• the inferred type is technically correct but inconvenient: do not assert it away. either redesign the api to make the type narrower (e.g. split a function into two, or add overloads), or accept the inconvenience and handle the union explicitly. inconvenient types are usually telling you something about the design.
• the error is in a generated file (graphql codegen, prisma, openapi, protobuf): do not edit the generated file. fix the schema or the codegen config upstream. re-run the codegen after the fix.
• the error only appears in ci or in a certain tsconfig, not locally: the tsconfig settings differ (strict mode, noImplicitAny, target, lib, module resolution). check tsconfig.json. if ci uses a stricter tsconfig, apply that tsconfig locally and re-run. do not commit code that only "works" in permissive tsconfig.
• narrowing is lost after an await or assignment in a closure: re-narrow inside the closure with a local const or a type guard function. typescript cannot track narrowing across async boundaries or into callback closures.

output contract

a fix that:

• resolves the original error reported by tsc
• does not introduce as any or @ts-ignore in production code (or if it does, it is commented with a real reason and a follow-up task is filed)
• leaves the type at least as narrow as before (ideally narrower)
• passes tsc --noEmit --strict cleanly
• does not add performance overhead or change runtime behavior

outcome signal

re-running the build is green. the next person who reads the code can see at the type level what the expression is, and how it got there. if your fix made them say "where is this type coming from" or "why did you use as any here", the fix is incomplete. a comment explaining the non-obvious part of the fix is a green light.

notes

• typescript errors at line N are almost never about line N. always walk upstream first.
• satisfies is the modern equivalent of "assert without losing inference". use it instead of as when you can. it was added in typescript 4.9.
• if you cannot reproduce the error in isolation, the problem is in the build config (tsconfig path mappings, multiple tsconfigs, project references, conditional exports). check your build, not your code.
• // $ExpectType <Type> is a debug tool. hover over an expression, or write // $ExpectType string on the next line, and typescript will error if the type does not match. use it to verify your hypothesis about what the type should be at a given point.
• avoid broad types in function signatures. if a parameter is any, unknown, or object, the function's return type and all assignments downstream will be too. be explicit.

---

credits: original skill by implexa.