hs-web/hsweb-framework · error · IllegalStateException

table or view " + tableName.getName() + " not found in " +…

Error message

table or view " + tableName.getName() + " not found in " + schemaMetadata.getName()

What it means

During SQL analysis, QueryAnalyzerImpl.visit(Table) resolves the table name against the current schema's metadata (and then any virtual tables). If the table/view is present in neither, it throws this IllegalStateException. This usually means the SQL references a table the analyzer doesn't know about — often because dynamic/virtual tables or the schema metadata weren't registered.

Solutions

Register the table (or a virtual table) in the schema metadata used by the analyzer.
Verify the table exists in the database schema the analyzer uses (check currentSchema).
Correct the table/view name spelling and schema qualification in the query.
Reload/refresh schema metadata after migrations, then retry.

Example fix

// before
SELECT * FROM order_item; // not in schemaMetadata or virtual tables -> IllegalStateException

// after
schemaMetadata.addTable(new TableOrViewMetadata("order_item"));
// or use the real registered table:
SELECT * FROM orders.order_item;

Defensive patterns

Strategy: validation

Validate before calling

// Java
if (!schemaMetadata.getTableOrView(tableName, false).isPresent()
    && virtualTableLookup(tableName) == null) {
    throw new IllegalArgumentException("unknown table: " + tableName);
}

Try / catch

// Java
try {
    analyzer.analyze(sql);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("not found in")) {
        schemaMetadata.reload(); // refresh metadata, then retry once
        analyzer.analyze(sql);
    } else { throw e; }
}

Prevention

Refresh schema metadata after every migration.
Register virtual/dynamic tables with the analyzer up front.
Qualify table names with the schema they actually live in.

When it happens

Trigger: Executing/analyzing a query whose FROM/JOIN references a table or view not registered in schemaMetadata and not present in the virtualTable map — e.g. table created after metadata was loaded, wrong schema, misspelled table name, or native SQL touching tables outside the analyzer's known schema.

Common situations: Schema migrations added a new table while the app kept stale metadata; multi-schema setups where the query targets a different schema than current; dynamic table sharding where virtual tables weren't registered with the analyzer; typos in hand-written SQL.

Related errors

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

Appendix: source

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

            schemaMetadata = database
                .getMetadata()
                .getSchema(schema)
                .orElseThrow(() -> new IllegalStateException("schema " + schema + " not initialized"));
        } else {
            schemaMetadata = database.getMetadata().getCurrentSchema();
            if (!virtualTable.containsKey(name)) {
                tableName.setSchemaName(schemaMetadata.getQuoteName());
            }
        }

        String alias = tableName.getAlias() == null ? tableName.getName() : tableName.getAlias().getName();

        TableOrViewMetadata tableMetadata = schemaMetadata
            .getTableOrView(name, false)
            .orElseGet(() -> virtualTable.get(name));

        if (tableMetadata == null) {
            throw new IllegalStateException("table or view " + tableName.getName() + " not found in " + schemaMetadata.getName());
        }
        tableName.setName(tableMetadata.getRealName());
        QueryAnalyzer.Table table = new QueryAnalyzer.Table(
            parsePlainName(alias),
            tableMetadata
        );

        select = new QueryAnalyzer.Select(new ArrayList<>(), table);

    }

    // select * from ( select a,b,c from table ) t
    @Override
    public void visit(SubSelect subSelect) {
        visit(subSelect, subSelect.getAlias() == null ? null : subSelect.getAlias().getName());
    }

    public void visit(SubSelect subSelect, String alias) {

View on GitHub (pinned to b2cfc85a57)