{"record":{"id":"17caa454ccf3e66a","repo":"apache/seatunnel","slug":"checking-catalog-path-s-exists-exception","errorCode":null,"errorMessage":"Checking catalog path %s exists exception.","messagePattern":"Checking catalog path (.+?) exists exception\\.","errorType":"exception","errorClass":"CatalogException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-hudi/src/main/java/org/apache/seatunnel/connectors/seatunnel/hudi/catalog/HudiCatalog.java","lineNumber":91,"sourceCode":"    private FileSystem fs;\n\n    public HudiCatalog(String catalogName, Configuration hadoopConf, String tableParentDfsPathStr) {\n        this.catalogName = catalogName;\n        this.hadoopConf = hadoopConf;\n        this.tableParentDfsPathStr = tableParentDfsPathStr;\n        this.tableParentDfsPath = new Path(tableParentDfsPathStr);\n    }\n\n    @Override\n    public void open() throws CatalogException {\n        fs = HadoopFSUtils.getFs(tableParentDfsPathStr, hadoopConf);\n        try {\n            if (!fs.exists(tableParentDfsPath)) {\n                log.info(\"Table dfs path not exists, will be created\");\n                fs.mkdirs(tableParentDfsPath);\n            }\n        } catch (IOException e) {\n            throw new CatalogException(\n                    String.format(\n                            \"Checking catalog path %s exists exception.\", tableParentDfsPathStr),\n                    e);\n        }\n        if (!databaseExists(getDefaultDatabase())) {\n            TablePath defaultDatabase = TablePath.of(getDefaultDatabase(), \"default\");\n            createDatabase(defaultDatabase, true);\n        }\n    }\n\n    @Override\n    public void close() throws CatalogException {\n        try {\n            if (fs != null) {\n                fs.close();\n            }\n        } catch (Exception e) {\n            log.info(\"Hudi catalog close error.\", e);","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-hudi/src/main/java/org/apache/seatunnel/connectors/seatunnel/hudi/catalog/HudiCatalog.java#L73-L109","documentation":"HudiCatalog.open verifies (and creates if needed) the filesystem directory that holds the catalog's databases. If checking fs.exists(tableParentDfsPath) throws an IOException, it is wrapped in this CatalogException with the path in the message. This usually means the configured warehouse/base path is unreachable or the filesystem is misconfigured.","triggerScenarios":"Calling open() on a HudiCatalog whose tableParentDfsPath cannot be probed: HDFS NameNode unreachable, S3/OSS credentials missing or wrong, bad scheme in the catalog base path (e.g. hdfs:// vs file://), or network partition.","commonSituations":"HDFS cluster down or NameNode in safe mode; AWS/S3 credentials not present on the SeaTunnel worker; typo in warehouse path URI; Kerberos/auth failure surfaced as IOException.","solutions":["Verify the filesystem URI in the catalog config is correct and reachable (e.g. hdfs dfs -ls <path>).","Check credentials/keys for the object store (S3/OSS) are configured on the worker running the job.","Confirm HDFS NameNode is up and out of safe mode if using HDFS.","Inspect the wrapped IOException cause in the stack trace for the root filesystem error.","Use file:// explicitly for local testing to rule out cluster issues."],"exampleFix":"// before\nwarehouse = \"hdfs://wrong-namenode:8020/hudi\"\n// after\nwarehouse = \"hdfs://namenode:8020/hudi\"","handlingStrategy":"try-catch","validationCode":"// probe the path before opening the catalog\norg.apache.hadoop.fs.FileSystem fs = org.apache.hadoop.fs.FileSystem.get(\n        new org.apache.hadoop.conf.Configuration());\nif (!fs.exists(new org.apache.hadoop.fs.Path(warehouseUri))) {\n    fs.mkdirs(new org.apache.hadoop.fs.Path(warehouseUri));\n}","typeGuard":null,"tryCatchPattern":"try {\n    catalog.open();\n} catch (CatalogException e) {\n    Throwable root = e;\n    while (root.getCause() != null) root = root.getCause();\n    throw new RuntimeException(\"Catalog path unreachable, root cause: \" + root.getMessage(), e);\n}","preventionTips":["Test the warehouse URI from the worker host (hdfs dfs -ls / aws s3 ls) before submitting jobs.","Keep object-store credentials in a standard, worker-accessible location (core-site.xml, env, IAM role).","Unwrap the IOException cause to identify filesystem vs credential vs network errors."],"tags":["filesystem","io","catalog","hdfs"],"backgroundTag":"file-read-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}