hs-web/hsweb-framework · error · IllegalArgumentException

join alias [" + alias + "] not found!

Error message

join alias [" + alias + "] not found!

What it means

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.

Solutions

1. Use the exact alias string that was declared when the join was created (match case).
2. Explicitly set an alias on the join, e.g. leftJoin(X.class, x -> ..., "x"), before referencing it.
3. Ensure you reference the alias on the same QuerySpec instance where the join was registered.
4. Print/inspect the joins list to see available aliases.

Example fix

// before
spec.where(nested -> nested.eq("u.name", "tom")); // alias "u" never declared

// after
spec.leftJoin(UserEntity.class, on -> on.eq("id", "userId"), "u")
    .where(nested -> nested.eq("u.name", "tom"));

// Java
String alias = "u";
boolean exists = spec.getJoins().stream()
    .anyMatch(j -> Objects.equals(j.getAlias(), alias));
if (!exists) throw new IllegalArgumentException("alias not declared: " + alias);

// Java
try {
    spec.join("u");
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("join alias")) {
        spec.leftJoin(UserEntity.class, on -> on.eq("id", "userId"), "u");
    } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• join class [" + clazz + "] not found!
• valuesList[" + valuesList + "] must have alias
• 不支持的验证规则:
• 不支持的授权请求:
• parentId

AI-assisted analysis of hs-web/hsweb-framework@b2cfc85a57 (2026-09-13). Data as JSON: /api/errors/e63111ebd26cd3fa. Report an issue: GitHub.

Appendix: source

Thrown at hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/query/DefaultQueryHelper.java:547

                    if (Objects.equals(join.mainClass, clazz)) {
                        return join;
                    }
                }
            }

            throw new IllegalArgumentException("join class [" + clazz + "] not found!");
        }

        private JoinConditionalSpecImpl getJoinByAlias(String alias) {
            if (joins != null) {
                for (JoinConditionalSpecImpl join : joins) {
                    if (Objects.equals(join.alias, alias)) {
                        return join;
                    }
                }
            }

            throw new IllegalArgumentException("join alias [" + alias + "] not found!");
        }

        @Override
        public <From> FromSpec<R> from(Class<From> clazz) {
            query = parent
                .database
                .dml()
                .query(table = parent.getTable(from = clazz));
            return this;
        }

        private QueryOperator createQuery() {
            QueryOperator query = this.query.clone();
            for (ColumnMapping<R> mapping : mappings) {
                query.select(mapping.forSelect());
            }
            return query;

View on GitHub (pinned to b2cfc85a57)