TypeScript unknown vs any: Differences, Safety, and When to Use Each

By the end of this page, you will understand how any and unknown differ in TypeScript, why unknown is safer, and when each type should be used. You will also see how unknown forces type checks before use, which helps prevent runtime errors in real applications.

any and unknown both represent values whose type is not known ahead of time, but they behave very differently.

• any turns off type checking for that value.
• unknown keeps the fact that the type is unknown, so TypeScript requires you to prove what it is before using it.

What any means

When a value is typed as any, TypeScript allows almost anything:

let value: any = "hello";
value.toUpperCase();
value.doesNotExist();
value();

TypeScript will not complain, even if the code is clearly unsafe. This makes any an escape hatch.

What unknown means

When a value is typed as unknown, TypeScript says:

"I know this value exists, but I do not know what it is yet."

Because of that, you cannot directly:

Think of these two types like packages.

• any is a package with no rules. You are allowed to open it, use it, or assume anything is inside.
• unknown is a sealed package with a warning label: "Contents not verified." You must inspect it before using it.

With any, TypeScript steps aside and says, "You are on your own."

With unknown, TypeScript says, "I will help you stay safe until you confirm what this value is."

The main difference appears when you try to use the value.

Basic syntax

let a: any;
let b: unknown;

Example: method calls

let valueAny: any = "hello";
let valueUnknown: unknown = "hello";

console.log(valueAny.toUpperCase()); // Allowed
// console.log(valueUnknown.toUpperCase()); // Error

valueUnknown.toUpperCase() fails because TypeScript does not yet know that valueUnknown is a string.

Narrowing unknown

let valueUnknown: unknown = "hello";

if (typeof valueUnknown === "string") {
  .(valueUnknown.()); 
}

Consider this example:

function shout(input: unknown) {
  if (typeof input === "string") {
    return input.toUpperCase();
  }

  return "NOT A STRING";
}

console.log(shout("hello"));
console.log(shout(123));

Step by step

1. The function parameter input is declared as unknown.
2. That means the function accepts any value, but cannot use it unsafely.
3. The if (typeof input === "string") check narrows input from unknown to string inside that block.
4. Inside the block, input.toUpperCase() is allowed because TypeScript now knows input is a string.
5. If the input is not a string, the function returns a fallback value.

API responses

When data comes from an external API, the shape may not be guaranteed.

async function fetchUser(): Promise<unknown> {
  const response = await fetch("/api/user");
  return response.json();
}

You can then validate the data before using it.

Parsing JSON

const raw = '{"name":"Ada"}';
const data: unknown = JSON.parse(raw);

JSON.parse() returns data that could be anything. Treating it as unknown is safer than trusting it immediately.

User input

Form values, query parameters, and CLI arguments often need validation before use.

Catching errors

In modern TypeScript, caught errors are often treated cautiously because they may not always be Error objects.

In real projects, unknown is commonly used at boundaries and any is avoided unless there is a strong reason.

Common patterns

1. Validation at the edges

Developers often accept unknown first, then validate.

function isUser(value: unknown): value is { name: string } {
  return (
    typeof value === "object" &&
    value !== null &&
    "name" in value
  );
}

2. Guard clauses

function greet(value: unknown) {
  if (typeof value !== "string") {
    return "Invalid name";
  }

  return `Hello, ${value}`;
}

This keeps unsafe values out of the main logic.

3. Error handling

1. Using any as the default for unknown data

Broken example:

function printName(user: any) {
  console.log(user.name.toUpperCase());
}

This compiles, but can crash if user.name is missing or not a string.

Safer version:

function printName(user: unknown) {
  if (
    typeof user === "object" &&
    user !== null &&
    "name" in user &&
    typeof (user as { name: unknown }).name === "string"
  ) {
    console.log((user as { name: string }).name.toUpperCase());
  }
}

unknown vs object

let x: any;
let y: unknown;

any

• Disables type checking for that value
• You can call methods, access properties, and assign it anywhere
• Useful as a last resort

let value: any = "hello";
value.toUpperCase();
value.notReal(); // still allowed by TypeScript

unknown

• Accepts any value
• Cannot be used directly until narrowed
• Safer than any

let value: unknown = "hello";

if (typeof value === "string") {
  value.toUpperCase();
}

Narrowing tools

• typeof

Is unknown safer than any in TypeScript?

Yes. unknown is safer because it forces you to check the value before using it.

Should I always use unknown instead of any?

In most cases, yes when the type is not known yet. Use any only when you intentionally want to bypass type checking.

Why does unknown cause errors when I access properties?

Because TypeScript does not know whether that property exists. You must narrow the type first.

Can unknown hold a string, number, or object?

Yes. unknown can store any value.

How do I convert unknown into a specific type?

Use type narrowing with checks like typeof, instanceof, or a custom type guard. You can also use a type assertion, but that is less safe.

When is any acceptable?

It can be acceptable during migration, when working around bad library typings, or in small isolated areas where strict typing is not practical.

• Type narrowing — unknown becomes useful through narrowing with checks like typeof and instanceof.
• Type guards — Custom type guard functions help safely convert unknown into specific types.
• Type assertions — Assertions can override TypeScript's understanding, but they are less safe than checks.
• Union types — Narrowing is also used heavily with union types.
• never — Useful to compare with unknown, since never represents impossible values.
• object type — Often confused with unknown, but they mean different things.
• Strict mode — Strong compiler settings make the benefits of unknown more visible.
• Error handling in TypeScript — Caught errors often need safe handling similar to unknown.