apache/shardingsphere · error · SingleTablesLoadingException

2

2

Error message

Can not load table with database name '%s' and data source name '%s'.

What it means

SingleTableDataNodeLoader.loadSchemaTableNames delegates to SchemaMetaDataLoader to enumerate tables in one storage unit; any SQLException from that metadata scan is wrapped in SingleTablesLoadingException (XOpen SQLState GENERAL_ERROR, code 2) naming the database and data source. The original driver exception is preserved as the cause.

Source

Thrown at kernel/single/core/src/main/java/org/apache/shardingsphere/single/datanode/SingleTableDataNodeLoader.java:237

    
    /**
     * Load schema table names.
     *
     * @param databaseName database name
     * @param storageType storage type
     * @param dataSource data source
     * @param dataSourceName data source name
     * @param includedTables included tables
     * @param excludedTables excluded tables
     * @return schema table names
     * @throws SingleTablesLoadingException Single tables loading exception
     */
    public static Map<String, Collection<String>> loadSchemaTableNames(final String databaseName, final DatabaseType storageType, final DataSource dataSource, final String dataSourceName,
                                                                       final Collection<String> includedTables, final Collection<String> excludedTables) {
        try {
            return new SchemaMetaDataLoader(storageType).loadSchemaTableNames(databaseName, dataSource, includedTables, excludedTables);
        } catch (final SQLException ex) {
            throw new SingleTablesLoadingException(databaseName, dataSourceName, ex);
        }
    }
}

View on GitHub (pinned to e952770a21)

Solutions

  1. Inspect getCause()/logged stack trace to see the underlying SQLException (auth, timeout, permission).
  2. Verify connectivity and credentials from the proxy host to that data source with the same JDBC URL.
  3. Grant the metadata user privileges to read information_schema (MySQL) or pg_catalog (PostgreSQL).
  4. Use a database and JDBC driver version supported by ShardingSphere single-table loading; if the engine cannot be scanned, configure NOT-LOADED tables or the single-table rule explicitly.
Defensive patterns

Strategy: try-catch

Validate before calling

try (Connection c = dataSource.getConnection(); Statement s = c.createStatement()) {
    s.execute("SELECT 1");
    // optionally verify metadata read privilege
    s.execute("SELECT 1 FROM information_schema.tables LIMIT 1");
} catch (SQLException e) { /* fix connectivity/privileges before adding unit */ }

Try / catch

try {
    SingleTableDataNodeLoader.loadSchemaTableNames(dbName, storageType, dataSource, dsName, included, excluded);
} catch (final SingleTablesLoadingException ex) {
    SQLException root = (SQLException) ex.getCause();
    // branch on root: auth failure, timeout, privilege
}

Prevention

When it happens

Trigger: During metadata loading of a single-table database: the loader connects to the given DataSource to list schemas/tables, and the driver throws — connection failure, missing privileges on information_schema/pg_catalog, unsupported catalog queries, or an unreadable metadata table.

Common situations: Wrong username/password or insufficient grants for metadata queries; network/firewall issues between proxy and storage; using a JDBC driver or database whose metadata queries the loader does not support; database restarted while metadata loads; connection pool exhaustion.

Related errors

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/fe4aea1072b39d43. Report an issue: GitHub.