Why am I getting an error Object literal may only specify known properties

Developers working with TypeScript often encounter a perplexing error message: “Object literal may only specify known properties.” This error, while initially cryptic, is a crucial indicator of TypeScript’s powerful type-checking system at work. It signifies that an object you’ve created, known as an object literal, contains properties not explicitly defined or expected by its assigned type. Understanding this error is fundamental for writing robust, type-safe code, especially when dealing with complex data structures or integrating with external APIs. This guide will demystify why you’re getting an error “Object literal may only specify known properties” and provide practical, actionable solutions to resolve it, ensuring your TypeScript projects remain both flexible and secure.

Understanding the “Object Literal May Only Specify Known Properties” Error

The “Object literal may only specify known properties” error is a cornerstone of TypeScript’s static type-checking capabilities. It arises when you attempt to assign an object literal to a variable or pass it as an argument, and that object literal includes properties that are not part of the target type’s definition. TypeScript enforces this rule to prevent common programming mistakes, such as typos in property names or accidentally introducing unintended data into an object that expects a specific structure. This strictness is a key benefit of using TypeScript over plain JavaScript, as it catches potential runtime errors during development.

At its core, this error is a manifestation of TypeScript’s “excess property checks” feature. When you create an object literal, TypeScript performs an extra validation step to ensure that all properties present in the literal are also present in the contextual type it’s being assigned to. This is particularly relevant when working with interfaces or type aliases, which explicitly define the shape of an object. Without this check, it would be easy to misspell a property name and have the code compile successfully, only to fail silently or unexpectedly at runtime when the application tries to access a non-existent property.

This error is less about preventing you from adding properties and more about ensuring that your code accurately reflects your type definitions. It’s a proactive measure that helps maintain data integrity and consistency throughout your application. For instance, if you define an interface for a User object with name and email properties, and then try to create a User object literal that also includes an unexpected age property, TypeScript will flag it. This prevents situations where a function expecting a User might inadvertently receive an object with additional, unhandled data.

Common Causes and Scenarios

The “Object literal may only specify known properties” error typically surfaces in a few common scenarios, all related to the mismatch between an object literal’s actual properties and the properties expected by its declared type. Understanding these root causes is the first step towards effectively resolving the issue and improving your TypeScript proficiency.

Mismatched Interfaces or Type Aliases

One of the most frequent reasons for this error is a discrepancy between the properties defined in an interface or type alias and the properties provided in an object literal. For example, if you have an interface Product that specifies id, name, and price, but your object literal includes an additional description property, TypeScript will report an error. This happens because the declared type acts as a contract, and the object literal is violating that contract by introducing properties not explicitly allowed. Developers often overlook this when quickly prototyping or refactoring, leading to type definition and implementation divergence.

interface Product { id: number; name: string; price: number; } const myProduct: Product = { id: 1, name: "Laptop", price: 1200, // description: "Powerful computing device" // Error: Object literal may only specify known properties }; 

Excess Property Checks

TypeScript employs a feature called “excess property checks” specifically for object literals. While TypeScript’s structural typing generally allows objects to have more properties than a target type (as long as they have at least all the required ones), this rule changes for object literals. When you’re directly assigning an object literal, TypeScript becomes stricter. It will not permit any properties in the literal that are not explicitly defined in the target type, even if those extra properties wouldn’t typically break structural compatibility in other contexts. This strictness is designed to catch common bugs like typos early in the development cycle, ensuring type safety and reducing unexpected behavior at runtime.

Typos and Unintended Properties

Sometimes, the cause is as simple as a typographical error. A developer might accidentally misspell a property name (e.g., emial instead of email), and because emial is not a “known property” in the interface, TypeScript flags it. This mechanism is incredibly helpful for catching such subtle bugs before they make it into production. Similarly, a property might be included unintentionally, perhaps copied from another object or left over from a refactor. The error acts as a safety net, prompting you to review your object’s structure against its intended type, thereby reinforcing good coding practices and precise type definitions.

When you encounter the “Object literal may only specify known properties” error, several strategies can help you resolve it. The best approach depends on your specific situation and intent. It’s crucial to understand why TypeScript is flagging the error before deciding on a fix, as simply suppressing it might hide deeper architectural issues.

1. Option 1: Update Your Type Definition

   If the additional properties in your object literal are intentional and part of the desired data structure, the most straightforward solution is to update your interface or type alias. This makes your type definition accurately reflect the shape of the objects you intend to create. This is the recommended approach for maintaining strict type safety and clarity.

   interface Product { id: number; name: string; price: number; description?: string; // Add the missing property } const myProduct: Product = { id: 1, name: "Laptop", price: 1200, description: "Powerful computing device" }; 
   

2. Option 2: Type Assertion (as Type)

   If you are certain that the excess properties are benign or will be handled elsewhere, you can use a type assertion to tell TypeScript to treat the object literal as a specific type, effectively bypassing the excess property check. This is often used when dealing with data coming from external sources or when you know more about the object’s shape than TypeScript can infer. However, use this with caution, as it can hide legitimate type errors. For example, const obj = { a: 1, b: 2 } as MyType; will force TypeScript to accept obj as MyType, even if MyType doesn’t have a b property. A safer alternative is to assert as unknown as Type if you’re transforming highly uncertain data.

3. Option 3: Index Signatures for Dynamic Properties

   When you expect an object to have dynamic or arbitrary properties not known at design time, an index signature can be added to your type definition. An index signature allows an object to be indexed with a string or number, returning a specified type. This is ideal for scenarios like configuration objects or dictionaries where property names aren’t fixed. For instance, interface Config { [key: string]: any; } will allow any string-keyed property with any value Question & Answer :

   I just upgraded from TypeScript 1.5 to the latest and I’m seeing an error in my code:

   interface Options { /* ... others ... */ callbackOnLocationHash?: boolean; } function f(opts: Options) { /* ... */ } // Error: Object literal may only specify known properties, // and 'callbackOnLoactionHash'does not exist in type 'Options'. f( { callbackOnLoactionHash: false }); 
   

   Code looks fine to me. What’s wrong?

   (Alternative universe version: I recognize the typo, and I really did mean to write that. What should I do to remove the error?)

   As of TypeScript 1.6, properties in object literals that do not have a corresponding property in the type they’re being assigned to are flagged as errors.

   Usually this error means you have a bug (typically a typo) in your code, or in the definition file. The right fix in this case would be to fix the typo. In the question, the property callbackOnLoactionHash is incorrect and should have been callbackOnLocationHash (note the mis-spelling of “Location”).

   This change also required some updates in definition files, so you should get the latest version of the .d.ts for any libraries you’re using.

   Example:

   interface TextOptions { alignment?: string; color?: string; padding?: number; } function drawText(opts: TextOptions) { ... } drawText({ align: 'center' }); // Error, no property 'align' in 'TextOptions' 
   

   But I meant to do that

   There are a few cases where you may have intended to have extra properties in your object. Depending on what you’re doing, there are several appropriate fixes

   Type-checking only some properties

   Sometimes you want to make sure a few things are present and of the correct type, but intend to have extra properties for whatever reason. Type assertions (<T>v or v as T) do not check for extra properties, so you can use them in place of a type annotation:

   interface Options { x?: string; y?: number; } // Error, no property 'z' in 'Options' let q1: Options = { x: 'foo', y: 32, z: 100 }; // OK let q2 = { x: 'foo', y: 32, z: 100 } as Options; // Still an error (good): let q3 = { x: 100, y: 32, z: 100 } as Options; 
   

   These properties and maybe more

   Some APIs take an object and dynamically iterate over its keys, but have ‘special’ keys that need to be of a certain type. Adding a string indexer to the type will disable extra property checking

   Before

   interface Model { name: string; } function createModel(x: Model) { ... } // Error createModel({name: 'hello', length: 100}); 
   

   After

   interface Model { name: string; [others: string]: any; } function createModel(x: Model) { ... } // OK createModel({name: 'hello', length: 100}); 
   

   This is a dog or a cat or a horse, not sure yet

   interface Animal { move; } interface Dog extends Animal { woof; } interface Cat extends Animal { meow; } interface Horse extends Animal { neigh; } let x: Animal; if(...) { x = { move: 'doggy paddle', woof: 'bark' }; } else if(...) { x = { move: 'catwalk', meow: 'mrar' }; } else { x = { move: 'gallop', neigh: 'wilbur' }; } 
   

   Two good solutions come to mind here

   Specify a closed set for x

   // Removes all errors let x: Dog|Cat|Horse; 
   

   or Type assert each thing

   // For each initialization x = { move: 'doggy paddle', woof: 'bark' } as Dog; 
   

   This type is sometimes open and sometimes not

   A clean solution to the “data model” problem using intersection types:

   interface DataModelOptions { name?: string; id?: number; } interface UserProperties { [key: string]: any; } function createDataModel(model: DataModelOptions & UserProperties) { /* ... */ } // findDataModel can only look up by name or id function findDataModel(model: DataModelOptions) { /* ... */ } // OK createDataModel({name: 'my model', favoriteAnimal: 'cat' }); // Error, 'ID' is not correct (should be 'id') findDataModel({ ID: 32 }); 
   

   See also https://github.com/Microsoft/TypeScript/issues/3755