hs-web/hsweb-framework · error · IllegalArgumentException

undefined column [" + column + "]

Error message

undefined column [" + column + "]

What it means

When building term (where-condition) fragments, the analyzer resolves the term's column via findColumn against the analyzed query. If no matching column is found in the FROM table, joins, or WITH items, an IllegalArgumentException `undefined column [...]` is thrown so invalid query parameters fail fast instead of generating broken SQL.

Solutions

1. Fix the term column name to match a column defined on the queried table or its joins.
2. Whitelist/validate query parameter names before converting them into Terms.
3. Add the missing column to the entity/table metadata if it should exist.

Example fix

// before
query.where("usrName", "jack")
// after
query.where("username", "jack")

if (analyzer.findColumn(term.getColumn()).isEmpty()) { throw new BadRequestException("unknown query field: " + term.getColumn()); }

try { return TERMS_BUILDER.createTermFragments(impl, term); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("undefined column")) { throw new BadRequestException(e.getMessage()); } throw e; }

When it happens

Trigger: Passing a Term whose `column` does not match any analyzed column, e.g. dynamic query terms built from request parameters with names like `unknownField` or `wrongAlias.field` that do not exist on the target table/joins.

Common situations: REST clients sending arbitrary query parameter names into dynamic-query endpoints; frontend renames a field while backend metadata is stale; typos in term column strings.

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

• parentId
• error.page_size_exceeded
• table or view " + tableName.getName() + " not found in " +…
• valuesList[" + valuesList + "] must have alias
• table function[" + tableFunction + "] must have alias

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

Appendix: source

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

//                            table = join.table;
//                            column = split[1];
//                        } else {
//                            throw new IllegalArgumentException("undefined column [" + column + "]");
//                        }
//                    }
//                }
//                RDBColumnMetadata columnMetadata = table
//                    .getMetadata()
//                    .getColumn(column)
//                    .orElse(null);
//                if (columnMetadata != null) {
//                    col = new Column(column, column, table.alias, columnMetadata);
//                } else {
//                    throw new IllegalArgumentException("undefined column [" + column + "]");
//                }
//            }
            if (col == null) {
                throw new IllegalArgumentException("undefined column [" + column + "]");
            }

            if (!Objects.equals(impl.select.table.alias, col.getOwner())) {
                QueryAnalyzer.Join join = impl.joins.get(col.getOwner());
                if (null != join) {
                    table = join.table;
                } else {
                    throw new IllegalArgumentException("undefined column [" + column + "]");
                }
            }

            FeatureSupportedMetadata metadata = col.metadata;
            if (col.metadata == null) {
                metadata = table.metadata;
            }

            String colName = col.metadata != null ? col.metadata.getRealName() : col.name;

View on GitHub (pinned to b2cfc85a57)