{"record":{"id":"7c32039f5f41581a","repo":"apache/shardingsphere","slug":"hy000-7c3203","errorCode":"HY000","errorMessage":"Load table meta data failed for database '%s'.","messagePattern":"Load table meta data failed for database '(.+?)'\\.","errorType":"exception","errorClass":"LoadTableMetaDataFailedException","httpStatus":null,"severity":"error","filePath":"mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/metadata/DatabaseMetaDataPersistFacade.java","lineNumber":116,"sourceCode":"    /**\n     * Register storage units.\n     *\n     * @param databaseName database name\n     * @param reloadMetaDataContexts reload meta data contexts\n     * @throws LoadTableMetaDataFailedException if an error occurs while loading table metadata\n     */\n    public void unregisterStorageUnits(final String databaseName, final MetaDataContexts reloadMetaDataContexts) {\n        ShardingSphereDatabase database = reloadMetaDataContexts.getMetaData().getDatabase(databaseName);\n        GenericSchemaBuilderMaterial material = new GenericSchemaBuilderMaterial(database.getResourceMetaData().getStorageUnits(),\n                database.getRuleMetaData().getRules(), reloadMetaDataContexts.getMetaData().getProps(), new DatabaseTypeRegistry(database.getProtocolType()).getDefaultSchemaName(databaseName),\n                database.getIdentifierContext(), database.getAllSchemas());\n        try {\n            Map<String, ShardingSphereSchema> schemas = GenericSchemaBuilder.build(database.getProtocolType(), material);\n            for (Entry<String, ShardingSphereSchema> entry : schemas.entrySet()) {\n                GenericSchemaManager.getToBeDroppedTables(entry.getValue(), database.getSchema(entry.getKey())).forEach(each -> table.drop(databaseName, entry.getKey(), each.getName()));\n            }\n        } catch (final SQLException ex) {\n            throw new LoadTableMetaDataFailedException(databaseName, ex);\n        }\n    }\n    \n    /**\n     * Persist altered tables.\n     *\n     * @param databaseName database name\n     * @param reloadMetaDataContexts reload meta data contexts\n     * @param needReloadTables need reload tables\n     * @return altered schema and tables map\n     * @throws LoadTableMetaDataFailedException if an error occurs while loading table metadata\n     */\n    public Map<String, Collection<ShardingSphereTable>> persistAlteredTables(final String databaseName, final MetaDataContexts reloadMetaDataContexts, final Collection<String> needReloadTables) {\n        ShardingSphereDatabase database = reloadMetaDataContexts.getMetaData().getDatabase(databaseName);\n        GenericSchemaBuilderMaterial material = new GenericSchemaBuilderMaterial(database.getResourceMetaData().getStorageUnits(),\n                database.getRuleMetaData().getRules(), reloadMetaDataContexts.getMetaData().getProps(),\n                new DatabaseTypeRegistry(database.getProtocolType()).getDefaultSchemaName(databaseName), database.getIdentifierContext(), database.getAllSchemas());\n        try {","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/metadata/DatabaseMetaDataPersistFacade.java#L98-L134","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    metaDataPersistFacade.unregisterStorageUnits(databaseName, contexts);\n} catch (final LoadTableMetaDataFailedException ex) {\n    SQLException cause = (SQLException) ex.getCause();\n    // restore connectivity/privileges for the failing datasource, then retry the unregister\n}","preventionTips":["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"],"tags":["metadata","storage-unit","schema-rebuild","sql"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}