apache/shardingsphere · error · LoadTableMetaDataFailedException
HY000
HY000
Error message
Load table meta data failed for database '%s'.
What it means
Thrown by DatabaseMetaDataPersistFacade.unregisterStorageUnits when rebuilding all schemas via GenericSchemaBuilder after storage units are unregistered fails with a SQLException; it is wrapped as LoadTableMetaDataFailedException for the given database (generic SQLState HY000). The rebuild computes tables to drop, so a failure here means table metadata could not even be loaded for the comparison.
Source
Thrown at mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/metadata/DatabaseMetaDataPersistFacade.java:116
/**
* Register storage units.
*
* @param databaseName database name
* @param reloadMetaDataContexts reload meta data contexts
* @throws LoadTableMetaDataFailedException if an error occurs while loading table metadata
*/
public void unregisterStorageUnits(final String databaseName, final MetaDataContexts reloadMetaDataContexts) {
ShardingSphereDatabase database = reloadMetaDataContexts.getMetaData().getDatabase(databaseName);
GenericSchemaBuilderMaterial material = new GenericSchemaBuilderMaterial(database.getResourceMetaData().getStorageUnits(),
database.getRuleMetaData().getRules(), reloadMetaDataContexts.getMetaData().getProps(), new DatabaseTypeRegistry(database.getProtocolType()).getDefaultSchemaName(databaseName),
database.getIdentifierContext(), database.getAllSchemas());
try {
Map<String, ShardingSphereSchema> schemas = GenericSchemaBuilder.build(database.getProtocolType(), material);
for (Entry<String, ShardingSphereSchema> entry : schemas.entrySet()) {
GenericSchemaManager.getToBeDroppedTables(entry.getValue(), database.getSchema(entry.getKey())).forEach(each -> table.drop(databaseName, entry.getKey(), each.getName()));
}
} catch (final SQLException ex) {
throw new LoadTableMetaDataFailedException(databaseName, ex);
}
}
/**
* Persist altered tables.
*
* @param databaseName database name
* @param reloadMetaDataContexts reload meta data contexts
* @param needReloadTables need reload tables
* @return altered schema and tables map
* @throws LoadTableMetaDataFailedException if an error occurs while loading table metadata
*/
public Map<String, Collection<ShardingSphereTable>> persistAlteredTables(final String databaseName, final MetaDataContexts reloadMetaDataContexts, final Collection<String> needReloadTables) {
ShardingSphereDatabase database = reloadMetaDataContexts.getMetaData().getDatabase(databaseName);
GenericSchemaBuilderMaterial material = new GenericSchemaBuilderMaterial(database.getResourceMetaData().getStorageUnits(),
database.getRuleMetaData().getRules(), reloadMetaDataContexts.getMetaData().getProps(),
new DatabaseTypeRegistry(database.getProtocolType()).getDefaultSchemaName(databaseName), database.getIdentifierContext(), database.getAllSchemas());
try {View on GitHub (pinned to e952770a21)
Solutions
- Check the cause SQLException for the failing datasource and SQL; restore connectivity/privileges for it before retrying the unregister.
- Unregister units one at a time and verify schema reload succeeds between steps to isolate the failing datasource.
- If the unit is permanently gone, clean up the persisted datasource configuration first so the rebuild no longer references it.
Defensive patterns
Strategy: try-catch
Try / catch
try {
metaDataPersistFacade.unregisterStorageUnits(databaseName, contexts);
} catch (final LoadTableMetaDataFailedException ex) {
SQLException cause = (SQLException) ex.getCause();
// restore connectivity/privileges for the failing datasource, then retry the unregister
} Prevention
- Keep every registered storage unit reachable, even ones about to be unregistered
- Remove persisted datasource config for permanently dead units before unregistering
- Verify schema reload after each unregister step
When it happens
Trigger: Unregistering storage units from a database whose remaining (or just-removed) datasources are unreachable, credentials are wrong, or the metadata queries GenericSchemaBuilder issues (information schema / catalog reads) fail on the storage engine.
Common situations: Unregistering a storage unit that is already down (so schema rebuild cannot read it), revoked privileges on system catalogs after a permissions sweep, or storage-database version changes that break metadata queries.
Related errors
AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14).
Data as JSON: /api/errors/7c32039f5f41581a.
Report an issue: GitHub.