apache/flink · error · IOException

Cannot instantiate file system for URI: ${fsUri}

Error message

Cannot instantiate file system for URI: ${fsUri}

What it means

A catch-all: any unexpected non-IOException exception during Hadoop filesystem creation (after scheme resolution and class loading succeeded) is wrapped in IOException('Cannot instantiate file system for URI: ...'). The real cause is attached as the nested exception and must be inspected to diagnose the failure.

Source

Thrown at flink-filesystems/flink-hadoop-fs/src/main/java/org/apache/flink/runtime/fs/hdfs/HadoopFsFactory.java:196

            HadoopFileSystem fs = new HadoopFileSystem(hadoopFs);

            // create the Flink file system, optionally limiting the open connections
            if (flinkConfig != null) {
                return limitIfConfigured(fs, scheme, flinkConfig);
            } else {
                return fs;
            }
        } catch (ReflectiveOperationException | LinkageError e) {
            throw new UnsupportedFileSystemSchemeException(
                    "Cannot support file system for '"
                            + fsUri.getScheme()
                            + "' via Hadoop, because Hadoop is not in the classpath, or some classes "
                            + "are missing from the classpath.",
                    e);
        } catch (IOException e) {
            throw e;
        } catch (Exception e) {
            throw new IOException("Cannot instantiate file system for URI: " + fsUri, e);
        }
    }

    private static String getMissingAuthorityErrorPrefix(URI fsURI) {
        return "The given file system URI ("
                + fsURI.toString()
                + ") did not describe the authority "
                + "(like for example HDFS NameNode address/port or S3 host). "
                + "The attempt to use a configured default authority failed: ";
    }

    private static FileSystem limitIfConfigured(
            HadoopFileSystem fs, String scheme, Configuration config) {
        final ConnectionLimitingSettings limitSettings =
                ConnectionLimitingSettings.fromConfig(config, scheme);

        // decorate only if any limit is configured
        if (limitSettings == null) {

View on GitHub (pinned to 2f3c205e92)

Solutions

  1. Read the nested cause of the thrown IOException — the fix depends entirely on it
  2. Fix the connector-specific configuration the cause points at (credentials, endpoints, kerberos)
  3. Upgrade the connector/Hadoop plugin if the cause is an internal bug (NPE etc.) known-fixed later
  4. Reproduce instantiation standalone: `hadoop fs -ls <scheme>://...` with the same jars/config to isolate Flink vs Hadoop issues
Defensive patterns

Strategy: try-catch

Try / catch

try {
    fs = FileSystem.get(uri);
} catch (IOException e) {
    if (e.getMessage().startsWith("Cannot instantiate file system")) {
        Throwable root = ExceptionUtils.getRootCause(e);
        // diagnose purely from root cause; surface it to the user verbatim
    }
}

Prevention

When it happens

Trigger: HadoopFsFactory.create throwing arbitrary RuntimeExceptions during fsClass.getConstructor().newInstance(), configuration wiring, or initialize() with non-IO failures; e.g. NPE inside the connector's constructor, IllegalArgument from misconfiguration, or security exceptions.

Common situations: Bad connector-specific config keys (S3 credentials, kerberos settings) causing constructor failures; connectors whose static initializers throw; partially-initialized Hadoop configs.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/8ba24543eb566665. Report an issue: GitHub.