{"record":{"id":"e63111ebd26cd3fa","repo":"hs-web/hsweb-framework","slug":"join-alias-alias-not-found","errorCode":null,"errorMessage":"join alias [\" + alias + \"] not found!","messagePattern":"join alias \\[\" \\+ alias \\+ \"\\] not found!","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/query/DefaultQueryHelper.java","lineNumber":547,"sourceCode":"                    if (Objects.equals(join.mainClass, clazz)) {\n                        return join;\n                    }\n                }\n            }\n\n            throw new IllegalArgumentException(\"join class [\" + clazz + \"] not found!\");\n        }\n\n        private JoinConditionalSpecImpl getJoinByAlias(String alias) {\n            if (joins != null) {\n                for (JoinConditionalSpecImpl join : joins) {\n                    if (Objects.equals(join.alias, alias)) {\n                        return join;\n                    }\n                }\n            }\n\n            throw new IllegalArgumentException(\"join alias [\" + alias + \"] not found!\");\n        }\n\n        @Override\n        public <From> FromSpec<R> from(Class<From> clazz) {\n            query = parent\n                .database\n                .dml()\n                .query(table = parent.getTable(from = clazz));\n            return this;\n        }\n\n        private QueryOperator createQuery() {\n            QueryOperator query = this.query.clone();\n            for (ColumnMapping<R> mapping : mappings) {\n                query.select(mapping.forSelect());\n            }\n            return query;\n","sourceCodeStart":529,"sourceCodeEnd":565,"githubUrl":"https://github.com/hs-web/hsweb-framework/blob/b2cfc85a57c70bf5b5cf6e7edae2d37102652ec8/hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/query/DefaultQueryHelper.java#L529-L565","documentation":"QuerySpec can resolve joins by alias: getJoinByAlias scans the registered joins for one whose alias equals the requested string. If none matches, this IllegalArgumentException is thrown, meaning the alias was never assigned to any join in this query.","triggerScenarios":"Calling spec.join(\"someAlias\") / from(alias) style APIs with an alias string that was never registered — e.g. alias mismatch in case (\"User\" vs \"user\"), alias defined on a different query instance, or the alias omitted when creating the join.","commonSituations":"Case-sensitivity mistakes between declared and referenced alias; alias referenced from a sub-query/parent query where it isn't visible; refactor changed the alias name; developer confused the table name with the alias.","solutions":["Use the exact alias string that was declared when the join was created (match case).","Explicitly set an alias on the join, e.g. leftJoin(X.class, x -> ..., \"x\"), before referencing it.","Ensure you reference the alias on the same QuerySpec instance where the join was registered.","Print/inspect the joins list to see available aliases."],"exampleFix":"// before\nspec.where(nested -> nested.eq(\"u.name\", \"tom\")); // alias \"u\" never declared\n\n// after\nspec.leftJoin(UserEntity.class, on -> on.eq(\"id\", \"userId\"), \"u\")\n    .where(nested -> nested.eq(\"u.name\", \"tom\"));","handlingStrategy":"validation","validationCode":"// Java\nString alias = \"u\";\nboolean exists = spec.getJoins().stream()\n    .anyMatch(j -> Objects.equals(j.getAlias(), alias));\nif (!exists) throw new IllegalArgumentException(\"alias not declared: \" + alias);","typeGuard":null,"tryCatchPattern":"// Java\ntry {\n    spec.join(\"u\");\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"join alias\")) {\n        spec.leftJoin(UserEntity.class, on -> on.eq(\"id\", \"userId\"), \"u\");\n    } else { throw e; }\n}","preventionTips":["Define aliases as shared string constants to avoid case/typo drift.","Always pass an explicit alias when creating joins.","Never reference an alias from a different QuerySpec instance."],"tags":["java","query","join","alias","illegal-argument"],"backgroundTag":"resource-not-found","analyzedSha":"b2cfc85a57c70bf5b5cf6e7edae2d37102652ec8","analyzedAt":"2026-09-13T09:05:02.172Z","contentChangedAt":"2026-09-13T09:05:02.172Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}