{"record":{"id":"70ac1d3a6caec83a","repo":"apache/shardingsphere","slug":"load-meta-data-for-schema-s-and-table-s-fail","errorCode":null,"errorMessage":"Load meta data for schema '%s' and table '%s' failed","messagePattern":"Load meta data for schema '(.+?)' and table '(.+?)' failed","errorType":"exception","errorClass":"PipelineInternalException","httpStatus":null,"severity":"error","filePath":"kernel/data-pipeline/core/src/main/java/org/apache/shardingsphere/data/pipeline/core/metadata/loader/StandardPipelineTableMetaDataLoader.java","lineNumber":72,"sourceCode":"public final class StandardPipelineTableMetaDataLoader implements PipelineTableMetaDataLoader {\n    \n    private final PipelineDataSource dataSource;\n    \n    private volatile IdentifierCasePolicy tableIdentifierCasePolicy;\n    \n    private final Map<TableMetaDataCacheKey, PipelineTableMetaData> tableMetaDataMap = new ConcurrentHashMap<>();\n    \n    @Override\n    public PipelineTableMetaData getTableMetaData(final String schemaName, final String tableName) {\n        String qualifiedSchemaName = getQualifiedSchemaName(schemaName, new DatabaseTypeRegistry(dataSource.getDatabaseType()));\n        PipelineTableMetaData result = findTableMetaData(qualifiedSchemaName, tableName);\n        if (null != result) {\n            return result;\n        }\n        try {\n            loadTableMetaData(qualifiedSchemaName, tableName);\n        } catch (final SQLException ex) {\n            throw new PipelineInternalException(String.format(\"Load meta data for schema '%s' and table '%s' failed\", schemaName, tableName), ex);\n        }\n        result = findTableMetaData(qualifiedSchemaName, tableName);\n        if (null == result) {\n            log.warn(\"Can not load meta data for table '{}'\", tableName);\n        }\n        return result;\n    }\n    \n    private void loadTableMetaData(final String schemaName, final String tableName) throws SQLException {\n        try (Connection connection = dataSource.getConnection()) {\n            Map<ShardingSphereIdentifier, PipelineTableMetaData> loadedTableMetaData = loadTableMetaData(connection, schemaName, tableName);\n            loadedTableMetaData.forEach((key, value) -> tableMetaDataMap.put(new TableMetaDataCacheKey(schemaName, key.getValue()), value));\n        }\n    }\n    \n    private Map<ShardingSphereIdentifier, PipelineTableMetaData> loadTableMetaData(final Connection connection, final String schemaName, final String tableNamePattern) throws SQLException {\n        Collection<String> tableNames = new LinkedList<>();\n        try (ResultSet resultSet = connection.getMetaData().getTables(connection.getCatalog(), schemaName, tableNamePattern, null)) {","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/kernel/data-pipeline/core/src/main/java/org/apache/shardingsphere/data/pipeline/core/metadata/loader/StandardPipelineTableMetaDataLoader.java#L54-L90","documentation":"StandardPipelineTableMetaDataLoader caches table metadata per (schema, table) and, on a cache miss, opens a connection and introspects the table; any SQLException from that introspection is wrapped in PipelineInternalException('Load meta data for schema X and table Y failed'). The original SQLException (carried as cause) explains the real problem: missing table, wrong schema, permission, or connection failure.","triggerScenarios":"Pipeline metadata loading (during job preparation or inventory) for a schema/table that does not exist on the source, a table name with case sensitivity mismatch, an unprivileged introspection call, or a dropped connection during getColumns/getPrimaryKeys.","commonSituations":"Schema/table name case mismatch on case-sensitive databases (PostgreSQL/openGauss lowercase folding); referencing a table dropped after job config was created; the pipeline user lacking metadata-reading privileges; transient network failures during job init.","solutions":["Read the cause exception to classify: unknown table vs permission vs connectivity.","Verify the exact schema and table names (case, quoting) exist on the source with SHOW TABLES / information_schema as the pipeline user.","Grant metadata-read privileges to the pipeline user and retry the job step.","For transient failures, retry/restart the pipeline job after connectivity is stable."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// preflight: confirm the table is introspectable as the pipeline user\ntry (Connection c = dataSource.getConnection()) {\n    DatabaseMetaData md = c.getMetaData();\n    try (ResultSet rs = md.getColumns(null, schemaName, tableName, null)) {\n        if (!rs.next()) {\n            throw new IllegalStateException(\"table not visible: \" + schemaName + \".\" + tableName);\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    PipelineTableMetaData meta = loader.getTableMetaData(schemaName, tableName);\n} catch (final PipelineInternalException ex) {\n    SQLException cause = (SQLException) ex.getCause();\n    // classify by cause.getErrorCode()/message: missing table, privileges, connectivity\n}","preventionTips":["Normalize schema/table names (case, quoting) to the source database's rules in job configuration.","Grant metadata-read privileges to the pipeline user up front.","Validate that all tables named in the job config still exist right before job start."],"tags":["pipeline","metadata","migration","wrapping-exception"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}