apache/shardingsphere · error · FileIOException

30020

30020

Error message

File access failed, file is: %s

What it means

FileIOException (error code 30020) thrown by ImportDatabaseConfigurationExecutor.getYamlProxyDatabaseConfiguration when YamlEngine.unmarshal(file, YamlProxyDatabaseConfiguration.class) fails with IOException during IMPORT DATABASE CONFIGURATION. The target file must be a readable YAML file on the proxy host before metadata import can proceed; any read failure is converted to this exception.

Source

Thrown at proxy/backend/core/src/main/java/org/apache/shardingsphere/proxy/backend/handler/distsql/ral/updatable/imports/ImportDatabaseConfigurationExecutor.java:48

import java.util.Collections;

/**
 * Import database configuration executor.
 */
public final class ImportDatabaseConfigurationExecutor implements DistSQLUpdateExecutor<ImportDatabaseConfigurationStatement> {
    
    @Override
    public void executeUpdate(final ImportDatabaseConfigurationStatement sqlStatement, final ContextManager contextManager) {
        YamlProxyDatabaseConfiguration yamlConfig = getYamlProxyDatabaseConfiguration(sqlStatement);
        new MetaDataImportExecutor(contextManager).importDatabaseConfigurations(Collections.singletonList(yamlConfig));
    }
    
    private YamlProxyDatabaseConfiguration getYamlProxyDatabaseConfiguration(final ImportDatabaseConfigurationStatement sqlStatement) {
        File file = new File(sqlStatement.getFilePath());
        try {
            return YamlEngine.unmarshal(file, YamlProxyDatabaseConfiguration.class);
        } catch (final IOException ignore) {
            throw new FileIOException(file);
        }
    }
    
    @Override
    public Class<ImportDatabaseConfigurationStatement> getType() {
        return ImportDatabaseConfigurationStatement.class;
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Copy or mount the exported YAML to a path the proxy can read, then re-run IMPORT DATABASE CONFIGURATION with that absolute path
2. Check file permissions (chmod/chown) for the proxy service user
3. Validate the file is regular YAML (not binary/corrupted) by opening it on the proxy host first

Example fix

-- before
IMPORT DATABASE CONFIGURATION FROM FILE 'export/db.yaml';

-- after
IMPORT DATABASE CONFIGURATION FROM FILE '/opt/shardingsphere/export/db.yaml';

File f = new File(path);
if (!f.isFile() || !f.canRead()) {
    throw new IllegalArgumentException("Import file missing or unreadable on proxy host: " + f.getAbsolutePath());
}
// then IMPORT DATABASE CONFIGURATION FROM FILE '<path>'

When it happens

Trigger: IMPORT DATABASE CONFIGURATION FROM FILE '/path' where the path is missing/unreadable/a directory, causing IOException from YamlEngine.unmarshal.

Common situations: Export/import workflow where the exported YAML was not copied to the target proxy node; containerized proxy without the host path mounted; permission mismatch between the exporting and importing environments.

Related errors

• 30020
• 30020
• 12010
• 12010
• 12011

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