hs-web/hsweb-framework · error · BusinessException.NoStackTrace

error.illegal_column_name

error.illegal_column_name

Error message

error.illegal_column_name

What it means

QueryHelperUtils.assertLegalColumn validates that a column identifier used in dynamic sorting/querying contains only legal characters (letters, digits, underscore, dot, backtick etc.). Anything else — typically SQL injection attempts like `name;drop table` or `name) and 1=1` — raises BusinessException with the message code `error.illegal_column_name`.

Solutions

  1. Sanitize the column identifier before passing it: allow only [A-Za-z0-9_.] and map camelCase to snake_case.
  2. Validate/sort parameters on the controller layer against a whitelist of sortable fields.
  3. Add the message key `error.illegal_column_name` to your i18n bundle so users see a readable message.

Example fix

// before
String col = request.getParam("sortBy"); // "name;drop table x"
QueryHelperUtils.assertLegalColumn(col);
// after
if (!col.matches("[a-zA-Z0-9_.]+")) { col = "id"; }
QueryHelperUtils.assertLegalColumn(col);
Defensive patterns

Strategy: try-catch

Validate before calling

if (col == null || !col.matches("[a-zA-Z0-9_.`]+")) { throw new BadRequestException("illegal column name"); }

Try / catch

try { QueryHelperUtils.assertLegalColumn(sortBy); } catch (BusinessException e) { if ("error.illegal_column_name".equals(e.getCode())) { throw new BadRequestException("invalid sort field"); } throw e; }

Prevention

When it happens

Trigger: Calling QueryHelperUtils.assertLegalColumn (directly or via QueryHelper sort/dynamic query processing) with a column string containing characters outside the allowed set, e.g. whitespace, parentheses, semicolons, quotes, or SQL keywords.

Common situations: Malicious or buggy clients passing raw query/sort parameters into hsweb dynamic query endpoints; i18n resource missing so only the code is shown; fields containing dashes from JSON-style naming.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

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

                    return _col;
                }
                if (c == '_') {
                    if (i == len - 1) {
                        builder.append('_');
                    } else {
                        builder.append(Character.toUpperCase(_col.charAt(++i)));
                    }
                } else {
                    builder.append(Character.toLowerCase(c));
                }
            }
            return builder.toString();
        });
    }

    public static void assertLegalColumn(String col) {
        if (!isLegalColumn(col)) {
            throw new BusinessException.NoStackTrace("error.illegal_column_name", col);
        }
    }

    public static boolean isLegalColumn(String col) {
        int len = col.length();
        for (int i = 0; i < len; i++) {
            char c = col.charAt(i);
            if (c == '_' || c == '$' || Character.isLetterOrDigit(c)) {
                continue;
            }
            return false;
        }
        return true;
    }
}

View on GitHub (pinned to b2cfc85a57)