Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

TypeORM cannot find an entity, or the metadata for a relation

ErrorEntity metadata for Role#users was not found.

Short answer

TypeORM only knows the entities listed in the entities option of the DataSource that is running. If a class, or a relation target, is missing from it, you get a missing-metadata error. Register every entity as a class or with a glob that matches the files you actually run: .ts under ts-node, .js after a build.

  • Applies to TypeORM 0.3.x, Node.js 22, TypeScript 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the entities the DataSource actually loaded. If the class from the error is not in the list, the cause is below.

    await AppDataSource.initialize()
    console.log(AppDataSource.entityMetadatas.map((m) => m.name))
  2. 2Match what you see, then jump to its fix

    1. 1The class in the error is missing from the printed listThe entity is not listed in the DataSource optionsFix
    2. 2The printed list is empty, but only after a build or only under ts-nodeThe glob matches .ts files but the app runs compiled .js, or the other way roundFix

What does the error look like?

  • Entity metadata for Role#users was not found.

Cause 1 of 2

The entity is not listed in the DataSource options

1Check

The docs say each entity must be registered in the data source options. A related entity, such as the other side of a relation, needs to be there too.

grep -n -A6 "entities" src/data-source.ts

2Fix

Add the class, or a glob that covers its file, to entities.

import { User } from "./entities/User"
import { Role } from "./entities/Role"

export const AppDataSource = new DataSource({
  // ...
  entities: [User, Role],
})

3Verify

Run the first-step print again; both classes appear.

npx ts-node src/check-entities.ts

Confirmed by typeorm.io

Did this fix it?

Cause 2 of 2

The glob matches .ts files but the app runs compiled .js, or the other way round

1Check

The data source docs show a pattern that ends in {.js,.ts} so that both modes work. A pattern that names only src/**/*.ts finds nothing inside dist/.

ls dist/entities 2>/dev/null
grep -n "entities" src/data-source.ts

2Fix

Use a path based on __dirname with both extensions, so it follows wherever the file runs from.

entities: [__dirname + "/entities/**/*{.ts,.js}"],

3Verify

Start the app from source and from the build; the entity list is the same.

npx ts-node src/check-entities.ts
node dist/check-entities.js

Confirmed by typeorm.io

Did this fix it?

How do I stop it coming back?

  • List entity classes explicitly in small projects; it removes glob mistakes.
  • Keep one DataSource definition and import it everywhere, including the CLI.
  • Add a startup log that prints the number of loaded entities.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.