How to fix Cannot assign to 'X' because it is a read-only property in TypeScript

What this error means

In TypeScript, the `readonly` keyword restricts properties from being assigned after their initial declaration. This is a compile-time safety feature that helps prevent unintended mutations. When you mark a property as `readonly`, TypeScript enforces that it can only be assigned: 1. At the point of declaration (inline) 2. In the class constructor 3. Never afterwards in instance methods or external code If you attempt to assign a new value to a readonly property anywhere else, TypeScript will emit error TS2540. This is a type-checking error only—it doesn't affect runtime behavior since JavaScript doesn't have a true readonly concept. Once compiled to JavaScript, the code will actually allow the assignment (which can lead to subtle bugs if you rely on readonly for immutability).

Typical symptoms

• TypeScript compiler shows 'Cannot assign to X because it is a read-only property'
• You're trying to modify an object property after it was created
• Error occurs in class instance methods or when mutating objects outside the class
• IDE shows red squiggly line under the assignment
• The error mentions a specific property name that you're trying to assign
• Code compiles and runs fine in JavaScript but fails TypeScript type checking

Common causes

1. Property is declared with the readonly modifier (most common)
2. Property comes from a readonly interface or type
3. Class property is declared as readonly and you're trying to modify it outside the constructor
4. You're trying to mutate a readonly object literal created with as const
5. Inherited readonly properties from a parent class are being modified
6. Using a third-party type definition with readonly constraints

How to fix "Cannot assign to 'X' because it is a read-only property"

interface User {
  readonly id: number;
  readonly name: string;
  email: string;
}

const user: User = { id: 1, name: "John", email: "john@example.com" };
user.id = 2; // Error: Cannot assign to 'id' because it is a read-only property

class Config {
  readonly apiUrl: string;

  constructor(url: string) {
    this.apiUrl = url; // OK: assignment in constructor
  }
}

const config = new Config("https://api.example.com");
config.apiUrl = "https://new-api.com"; // Error: Cannot assign

// Before
interface User {
  readonly id: number;
  readonly name: string;
}

// After
interface User {
  id: number;      // readable and writable
  name: string;
}

const user: User = { id: 1, name: "John" };
user.id = 2;       // Now OK

interface User {
  readonly id: number;
  readonly name: string;
  readonly email: string;
}

const user: User = { id: 1, name: "John", email: "john@example.com" };

// Don't mutate; create a new object
const updatedUser: User = {
  ...user,
  email: "john.new@example.com",
};

// user.email is still "john@example.com" (unchanged)
// updatedUser.email is "john.new@example.com" (new object)

type Mutable<T> = {
  -readonly [P in keyof T]: T[P];
};

interface User {
  readonly id: number;
  readonly name: string;
}

// Create a mutable version
const user: Mutable<User> = { id: 1, name: "John" };
user.id = 2;         // Now OK
user.name = "Jane";  // Now OK

interface User {
  readonly id: number;
  readonly name: string;
}

const user: User = { id: 1, name: "John" };

// Type assertion bypasses the readonly check
(user as { id: number; name: string }).id = 2;

// Or more directly:
(user as any).id = 2;

class Config {
  readonly apiUrl: string;
  readonly timeout: number;

  constructor(url: string, timeout: number) {
    // These assignments in the constructor are allowed
    this.apiUrl = url;
    this.timeout = timeout;
  }

  updateUrl(newUrl: string) {
    // This would error:
    // this.apiUrl = newUrl;

    // Instead, create a new instance:
    return new Config(newUrl, this.timeout);
  }
}

Advanced notes

// TypeScript (with readonly)
interface User {
  readonly id: number;
}

const user: User = { id: 1 };
user.id = 2; // TS2540 error

// Compiled JavaScript (no readonly concept exists)
const user = { id: 1 };
user.id = 2; // Actually runs fine!

const readonlyArray: readonly string[] = ["a", "b", "c"];
readonlyArray.push("d");  // Error: Property 'push' does not exist on type 'readonly string[]'

const readonlyTuple: readonly [number, string] = [1, "a"];
readonlyTuple[0] = 2;     // Error: Cannot assign to '0' because it is a read-only property

interface User {
  readonly id: number;
  readonly name: string;
}

const user: Readonly<User> = Object.freeze({ id: 1, name: "John" });
// Now it's both type-safe (readonly) and runtime-protected (frozen)

Frequently asked questions

What does "TS2540" mean?

In TypeScript, the readonly keyword restricts properties from being assigned after their initial declaration. This is a compile-time safety feature that helps prevent unintended mutations. When you mark a property as readonly, TypeScript enforces that it can only be assigned: 1.

How do I fix "TS2540"?

This TypeScript error occurs when you try to modify a property marked with the readonly modifier. The fix involves either removing the readonly modifier, creating a new object instead of mutating, or using a type utility to strip readonly from properties.

What causes "TS2540"?

Property is declared with the readonly modifier (most common) Property comes from a readonly interface or type Class property is declared as readonly and you're trying to modify it outside the constructor

Is the "TS2540" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Cannot augment module 'X' outside of its own definition

  Cannot augment module outside of its own definition

  MEDIUM

• Cannot assign an abstract constructor type to a non-abstract constructor type

  How to fix "Cannot assign an abstract constructor type to a non-abstract constructor type" in TypeScript

  MEDIUM

• Cannot augment module 'X' with a non-module declaration

  Cannot augment module 'X' with a non-module declaration

  MEDIUM

• Cannot access protected property 'x' from outside the class

  How to fix "Cannot access protected property" error in TypeScript

  MEDIUM

• Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

  How to fix "Cannot find name 'process'" in TypeScript

  MEDIUM

• Module has no exported member 'X'

  How to fix 'Module has no exported member X' error in TypeScript

  MEDIUM

Official resources & further reading

• 📚TypeScript Official Documentation
• 📖
  TypeScript Handbook - Object Types (readonly properties)(Official Docs)
• 📖
  TypeScript Handbook - Mapped Types (-readonly modifier)(Official Docs)
• Understanding Why TypeScript Cannot Assign to Readonly Property
• Cannot assign to readonly property - Bobby Hadz
• Read-Only Properties in TypeScript - Marius Schulz
• Cannot assign to readonly properties from outside the class - Stack Overflow
• 🐙
  Cannot assign to readonly property when using type guard in ctor - GitHub(GitHub)