{"record":{"id":"8ba24543eb566665","repo":"apache/flink","slug":"cannot-instantiate-file-system-for-uri-fsuri","errorCode":null,"errorMessage":"Cannot instantiate file system for URI: ${fsUri}","messagePattern":"Cannot instantiate file system for URI: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"flink-filesystems/flink-hadoop-fs/src/main/java/org/apache/flink/runtime/fs/hdfs/HadoopFsFactory.java","lineNumber":196,"sourceCode":"            HadoopFileSystem fs = new HadoopFileSystem(hadoopFs);\n\n            // create the Flink file system, optionally limiting the open connections\n            if (flinkConfig != null) {\n                return limitIfConfigured(fs, scheme, flinkConfig);\n            } else {\n                return fs;\n            }\n        } catch (ReflectiveOperationException | LinkageError e) {\n            throw new UnsupportedFileSystemSchemeException(\n                    \"Cannot support file system for '\"\n                            + fsUri.getScheme()\n                            + \"' via Hadoop, because Hadoop is not in the classpath, or some classes \"\n                            + \"are missing from the classpath.\",\n                    e);\n        } catch (IOException e) {\n            throw e;\n        } catch (Exception e) {\n            throw new IOException(\"Cannot instantiate file system for URI: \" + fsUri, e);\n        }\n    }\n\n    private static String getMissingAuthorityErrorPrefix(URI fsURI) {\n        return \"The given file system URI (\"\n                + fsURI.toString()\n                + \") did not describe the authority \"\n                + \"(like for example HDFS NameNode address/port or S3 host). \"\n                + \"The attempt to use a configured default authority failed: \";\n    }\n\n    private static FileSystem limitIfConfigured(\n            HadoopFileSystem fs, String scheme, Configuration config) {\n        final ConnectionLimitingSettings limitSettings =\n                ConnectionLimitingSettings.fromConfig(config, scheme);\n\n        // decorate only if any limit is configured\n        if (limitSettings == null) {","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-filesystems/flink-hadoop-fs/src/main/java/org/apache/flink/runtime/fs/hdfs/HadoopFsFactory.java#L178-L214","documentation":"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.","triggerScenarios":"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.","commonSituations":"Bad connector-specific config keys (S3 credentials, kerberos settings) causing constructor failures; connectors whose static initializers throw; partially-initialized Hadoop configs.","solutions":["Read the nested cause of the thrown IOException — the fix depends entirely on it","Fix the connector-specific configuration the cause points at (credentials, endpoints, kerberos)","Upgrade the connector/Hadoop plugin if the cause is an internal bug (NPE etc.) known-fixed later","Reproduce instantiation standalone: `hadoop fs -ls <scheme>://...` with the same jars/config to isolate Flink vs Hadoop issues"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    fs = FileSystem.get(uri);\n} catch (IOException e) {\n    if (e.getMessage().startsWith(\"Cannot instantiate file system\")) {\n        Throwable root = ExceptionUtils.getRootCause(e);\n        // diagnose purely from root cause; surface it to the user verbatim\n    }\n}","preventionTips":["Always log the full exception chain for filesystem setup failures","Smoke-test filesystem creation at job startup rather than mid-stream","Keep connector configs (credentials, endpoints) validated by config checks"],"tags":["hdfs","wrapper-exception","configuration","initialization"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}