{"record":{"id":"8a168f69ed32f3f3","repo":"hs-web/hsweb-framework","slug":"table-or-view-tablename-getname-not-found-in-schemametadata","errorCode":null,"errorMessage":"table or view \" + tableName.getName() + \" not found in \" + schemaMetadata.getName()","messagePattern":"table or view \" \\+ tableName\\.getName\\(\\) \\+ \" not found in \" \\+ schemaMetadata\\.getName\\(\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/query/QueryAnalyzerImpl.java","lineNumber":279,"sourceCode":"            schemaMetadata = database\n                .getMetadata()\n                .getSchema(schema)\n                .orElseThrow(() -> new IllegalStateException(\"schema \" + schema + \" not initialized\"));\n        } else {\n            schemaMetadata = database.getMetadata().getCurrentSchema();\n            if (!virtualTable.containsKey(name)) {\n                tableName.setSchemaName(schemaMetadata.getQuoteName());\n            }\n        }\n\n        String alias = tableName.getAlias() == null ? tableName.getName() : tableName.getAlias().getName();\n\n        TableOrViewMetadata tableMetadata = schemaMetadata\n            .getTableOrView(name, false)\n            .orElseGet(() -> virtualTable.get(name));\n\n        if (tableMetadata == null) {\n            throw new IllegalStateException(\"table or view \" + tableName.getName() + \" not found in \" + schemaMetadata.getName());\n        }\n        tableName.setName(tableMetadata.getRealName());\n        QueryAnalyzer.Table table = new QueryAnalyzer.Table(\n            parsePlainName(alias),\n            tableMetadata\n        );\n\n        select = new QueryAnalyzer.Select(new ArrayList<>(), table);\n\n    }\n\n    // select * from ( select a,b,c from table ) t\n    @Override\n    public void visit(SubSelect subSelect) {\n        visit(subSelect, subSelect.getAlias() == null ? null : subSelect.getAlias().getName());\n    }\n\n    public void visit(SubSelect subSelect, String alias) {","sourceCodeStart":261,"sourceCodeEnd":297,"githubUrl":"https://github.com/hs-web/hsweb-framework/blob/b2cfc85a57c70bf5b5cf6e7edae2d37102652ec8/hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/query/QueryAnalyzerImpl.java#L261-L297","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nSELECT * FROM order_item; // not in schemaMetadata or virtual tables -> IllegalStateException\n\n// after\nschemaMetadata.addTable(new TableOrViewMetadata(\"order_item\"));\n// or use the real registered table:\nSELECT * FROM orders.order_item;","handlingStrategy":"validation","validationCode":"// Java\nif (!schemaMetadata.getTableOrView(tableName, false).isPresent()\n    && virtualTableLookup(tableName) == null) {\n    throw new IllegalArgumentException(\"unknown table: \" + tableName);\n}","typeGuard":null,"tryCatchPattern":"// Java\ntry {\n    analyzer.analyze(sql);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"not found in\")) {\n        schemaMetadata.reload(); // refresh metadata, then retry once\n        analyzer.analyze(sql);\n    } else { throw e; }\n}","preventionTips":["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."],"tags":["java","sql","query-analyzer","table-not-found"],"backgroundTag":"table-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"}