{"id":"59270c09900c910d","repo":"typeorm/typeorm","slug":"whereentity-method-can-only-be-used-on-queries-wh-59270c","errorCode":null,"errorMessage":".whereEntity method can only be used on queries which update real entity table.","messagePattern":"\\.whereEntity method can only be used on queries which update real entity table\\.","errorType":"exception","errorClass":"TypeORMError","httpStatus":null,"severity":"error","filePath":"src/query-builder/UpdateQueryBuilder.ts","lineNumber":477,"sourceCode":"     * Sets LIMIT - maximum number of rows to be selected.\n     *\n     * @param limit\n     */\n    limit(limit?: number): this {\n        this.expressionMap.limit = this.validateNumericInput(\"limit\", limit)\n        return this\n    }\n\n    /**\n     * Indicates if entity must be updated after update operation.\n     * This may produce extra query or use RETURNING / OUTPUT statement (depend on database).\n     * Enabled by default.\n     *\n     * @param entity\n     */\n    whereEntity(entity: Entity | Entity[]): this {\n        if (!this.expressionMap.mainAlias!.hasMetadata)\n            throw new TypeORMError(\n                `.whereEntity method can only be used on queries which update real entity table.`,\n            )\n\n        this.expressionMap.wheres = []\n        const entities: Entity[] = Array.isArray(entity) ? entity : [entity]\n        entities.forEach((entity) => {\n            const entityIdMap =\n                this.expressionMap.mainAlias!.metadata.getEntityIdMap(entity)\n            if (!entityIdMap)\n                throw new TypeORMError(\n                    `Provided entity does not have ids set, cannot perform operation.`,\n                )\n\n            this.orWhereInIds(entityIdMap)\n        })\n\n        this.expressionMap.whereEntities = entities\n        return this","sourceCodeStart":459,"sourceCodeEnd":495,"githubUrl":"https://github.com/typeorm/typeorm/blob/04ff4daedcf60fa4ffd0d5d33bbafaac1a9bbc96/src/query-builder/UpdateQueryBuilder.ts#L459-L495","documentation":"Thrown by UpdateQueryBuilder.whereEntity() when the mainAlias has no entity metadata. whereEntity needs primary-key columns from real entity metadata to build the OR-IN list, so it refuses queries built from raw table-name strings or aliases without a bound entity class.","triggerScenarios":"Calling qb.update().set(...).whereEntity(entity) on a builder created via createQueryBuilder('raw_table') (string) or createQueryBuilder<Dto>() without an entity target. The hasMetadata check fails and throws.","commonSituations":"Updating a raw/non-entity table; using a DTO generic without registering the entity; refactoring that drops the entity argument; generic update helpers that accept any alias.","solutions":["Build the update from a registered entity: dataSource.getRepository(MyEntity).createQueryBuilder().update().","Ensure the entity class is in the DataSource entities list.","For raw tables, use where() with explicit conditions instead of whereEntity().","Verify mainAlias.target is the entity class before calling whereEntity."],"exampleFix":"// before — string table, no metadata\nawait dataSource.createQueryBuilder()\n  .update()\n  .set({ views: () => 'views + 1' })\n  .whereEntity(post)\n  .execute();\n\n// after — entity-backed builder\nawait dataSource.getRepository(Post).createQueryBuilder()\n  .update()\n  .set({ views: () => 'views + 1' })\n  .whereEntity(post)\n  .execute();","handlingStrategy":"validation","validationCode":"const qb = repo.createQueryBuilder().update().set({ views: () => 'views + 1' });\nif (!qb.expressionMap.mainAlias?.hasMetadata) {\n  throw new Error('whereEntity requires an entity-backed update builder');\n}\nqb.whereEntity(post);","typeGuard":"function isEntityBacked(qb: import('typeorm').QueryBuilder<any>): boolean {\n  return !!qb.expressionMap.mainAlias?.hasMetadata;\n}","tryCatchPattern":null,"preventionTips":["Build update queries from a registered entity repository.","Avoid raw table-name string aliases for update().whereEntity().","Register target entities in the DataSource entities array."],"tags":["where-entity","update-query","entity-metadata","query-builder"],"analyzedSha":"04ff4daedcf60fa4ffd0d5d33bbafaac1a9bbc96","analyzedAt":"2026-08-03T18:27:32.281Z","schemaVersion":2}