{"record":{"id":"c8e08a8d205be563","repo":"n8n-io/n8n","slug":"cannot-get-entity-metadata-for-the-given-alias","errorCode":null,"errorMessage":"Cannot get entity metadata for the given alias \"${this.name}\"","messagePattern":"Cannot get entity metadata for the given alias \"(.+?)\"","errorType":"exception","errorClass":"TypeORMError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/typeorm/src/query-builder/Alias.ts","lineNumber":43,"sourceCode":"\t}\n\n\tprivate _metadata?: EntityMetadata;\n\n\tget target(): Function | string {\n\t\treturn this.metadata.target;\n\t}\n\n\tget hasMetadata(): boolean {\n\t\treturn !!this._metadata;\n\t}\n\n\tset metadata(metadata: EntityMetadata) {\n\t\tthis._metadata = metadata;\n\t}\n\n\tget metadata(): EntityMetadata {\n\t\tif (!this._metadata)\n\t\t\tthrow new TypeORMError(`Cannot get entity metadata for the given alias \"${this.name}\"`);\n\n\t\treturn this._metadata;\n\t}\n}\n","sourceCodeStart":25,"sourceCodeEnd":48,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/typeorm/src/query-builder/Alias.ts#L25-L48","documentation":"The Alias.metadata getter throws when its private _metadata field is undefined. An Alias only carries EntityMetadata when it was resolved against a registered entity target; aliases created from raw table names, subquery strings, or SQL fragments have no metadata. Any code path that dereferences .metadata on such an alias (e.g. column resolution, relation lookup, alias.target) hits this guard.","triggerScenarios":"Accessing .metadata (directly or via .target which calls it) on an Alias built from a raw table path in createQueryBuilder().from('raw_table_name') or a subquery alias. Internally raised when QueryBuilder resolves column paths against a FROM alias that has no entity, or when join metadata resolution fails to bind the target to a registered entity.","commonSituations":"Using createQueryBuilder on a raw/non-entity table and then calling methods that need entity columns (addSelect with property paths, orderBy on columns). Refactoring an entity into a View or raw table without registering it. Accidentally passing a string table name where an entity class/function is expected.","solutions":["Register the target as a proper @Entity so the Alias resolves metadata; use the entity class or function reference instead of a raw table name.","Use raw SQL fragments (addSelect('alias.column', 'key').getRawMany()) instead of property-path methods when querying non-entity tables.","Check alias.hasMetadata before accessing alias.metadata if you must handle both cases.","Ensure the DataSource that owns this QueryBuilder actually has the entity registered in its entities array."],"exampleFix":"// before\nconst qb = dataSource\n  .createQueryBuilder()\n  .from('user_audit_log', 'log')\n  .orderBy('log.createdAt'); // .orderBy may need metadata\n\n// after — register entity, or use raw select\nconst rows = dataSource\n  .createQueryBuilder()\n  .select('log.created_at', 'createdAt')\n  .from('user_audit_log', 'log')\n  .orderBy('log.created_at')\n  .getRawMany();","handlingStrategy":"type-guard","validationCode":"const isEntityTarget = (target: unknown): target is Function | string =>\n  typeof target === 'function' || (typeof target === 'string' && dataSource.entityMetadatas.some(m => m.targetName === target));\nif (!isEntityTarget(target)) throw new Error('target is not a registered entity; use raw select');","typeGuard":"function aliasHasMetadata(alias: { hasMetadata: boolean }): alias is { hasMetadata: true; metadata: import('../metadata/EntityMetadata').EntityMetadata } {\n  return alias.hasMetadata;\n}","tryCatchPattern":null,"preventionTips":["Prefer createQueryBuilder(Entity, 'alias') with a registered entity over raw table strings.","For raw tables, use getRawMany() with explicit column-name selects, not property-path methods.","Ensure every entity is listed in DataSourceOptions.entities.","Guard metadata-dependent calls with alias.hasMetadata before access."],"tags":["query-builder","alias","metadata","entity"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}