apache/seatunnel · error · PaimonConnectorException

LOAD_CATALOG

LOAD_CATALOG

Error message

${e.message}

What it means

loadCatalog wraps any exception raised while creating the Paimon catalog into a SeaTunnel PaimonConnectorException with code LOAD_CATALOG, propagating the underlying exception's message. This is the generic failure path for catalog creation: bad warehouse path, invalid paimon-conf, metastore connection failures, the privilege credential check, plugin/config errors, etc. The real reason is in the message and wrapped cause.

Source

Thrown at seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/catalog/PaimonCatalogLoader.java:120

        final CatalogContext catalogContext =
                CatalogContext.create(options, paimonHadoopConfiguration);
        try {
            // If paimon privilege enabled, there will be system tables named user.sys and
            // privilege.sys in the warehouse.
            // It returns a PrivilegedCatalog. Otherwise, it returns a CachingCatalog.
            // If paimon privilege enabled, perform user and password verification accordingly.
            Catalog catalog =
                    PaimonSecurityContext.runSecured(
                            () -> CatalogFactory.createCatalog(catalogContext));
            if (catalog instanceof PrivilegedCatalog
                    && StringUtils.isBlank(user)
                    && StringUtils.isBlank(password)) {
                throw new IllegalArgumentException(
                        "paimon privilege is enabled, user and password is required");
            }
            return catalog;
        } catch (Exception e) {
            throw new PaimonConnectorException(
                    PaimonConnectorErrorCode.LOAD_CATALOG, e.getMessage(), e);
        }
    }

    void checkConfiguration(Configuration configuration, String key) {
        Iterator<Map.Entry<String, String>> entryIterator = configuration.iterator();
        while (entryIterator.hasNext()) {
            Map.Entry<String, String> entry = entryIterator.next();
            if (entry.getKey().equals(key)) {
                if (StringUtils.isBlank(entry.getValue())) {
                    throw new IllegalArgumentException("The value of" + key + " is required");
                }
                return;
            }
        }
        throw new IllegalArgumentException(key + " is required");
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the wrapped cause / e.getMessage() to identify the root failure and fix that underlying issue.
2. Verify warehouse path, catalog type (filesystem/hive), and paimon-conf-dir settings in the SeaTunnel config.
3. Check metastore/HDFS/Kerberos connectivity and credentials from the SeaTunnel node.
4. Ensure the Paimon connector plugin is correctly installed (install-plugin.sh) with matching Paimon/Hadoop versions.

Example fix

// before
Paimon {
  warehouse = "hdfs://wrong-ns/paimon"
}
// after
Paimon {
  warehouse = "hdfs://correct-ns/paimon"
  catalog-name = "paimon"
  paimon-conf-dir = "/opt/paimon/conf"
}

// pre-flight: verify conf and warehouse reachability
Files.checkAccess(Paths.get(paimonConfDir, "paimon.properties"));
// e.g. ping Hive metastore URI / filesystem before loadCatalog()

try {
    Catalog c = loader.loadCatalog();
} catch (PaimonConnectorException e) {
    if (e.getErrorCode() == PaimonConnectorErrorCode.LOAD_CATALOG) {
        LOG.error("catalog init failed: {}", e.getCause(), e);
    }
    throw e;
}

When it happens

Trigger: Any failure inside CatalogFactory.createCatalog(catalogContext) (via PaimonSecurityContext.runSecured) or in option parsing before it — e.g. unreachable Hive metastore, invalid warehouse path, Hadoop/Kerberos errors, missing user/password for PrivilegedCatalog.

Common situations: Wrong warehouse URI or filesystem not on the classpath; Hive metastore down or wrong URI; Kerberos/HDFS permission issues; missing paimon-conf-dir; invalid option names in the catalog config; Hadoop classes missing from the plugin install.

Related errors

• Failed to open catalog %s
• Failed to open MongoDB Catalog: ${e.getMessage()}
• Database ${databaseName} does not exist in catalog ${catalog
• Table ${tablePath} does not exist in catalog ${catalogName}
• Table ${tablePath} already exists in catalog ${catalogName}

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/2ef81f6181158b9b. Report an issue: GitHub.