apache/seatunnel · error · IllegalArgumentException

Failed to config. Please check your configuration.

Error message

Failed to %s config. Please check your configuration.

What it means

ConfigShadeUtils.processConfig applies a config encryption/decryption plugin identified by 'shade.identifier'. When the plugin throws, it logs the real cause but rethrows an IllegalArgumentException with a sanitized message so sensitive material never leaks, appending the original exception as the cause.

Solutions

  1. Verify shade.identifier matches the plugin actually used to encrypt the values
  2. Re-encrypt the sensitive values with the same identifier/algorithm
  3. Check the cause exception (logged server-side) for the underlying crypto error

Example fix

// before
env { shade.identifier = "base64" }  # but values were encrypted with aes
// after
env { shade.identifier = "aes" }  # or re-encrypt values using base64
Defensive patterns

Strategy: try-catch

Validate before calling

// verify identifier is known before processing
Set<String> known = Set.of("base64", "aes", "sm4", "none"); if (!known.contains(shadeIdentifier)) throw new IllegalArgumentException("Unknown shade.identifier: " + shadeIdentifier);

Try / catch

try { decryptConfig(config); } catch (IllegalArgumentException e) { log.error("Shade processing failed: {}", e.getMessage(), e.getCause()); }

Prevention

When it happens

Trigger: Calling encryptConfig/decryptConfig on a config whose shade.identifier names a plugin that fails (e.g. unknown identifier, wrong base64 data, bad key/algorithm config).

Common situations: Typo'd shade.identifier (e.g. 'base64' vs 'base64Decode'), encrypting a password with a different plugin than used to decrypt, malformed encrypted values in the HOCON file.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-core/seatunnel-core-starter/src/main/java/org/apache/seatunnel/core/starter/utils/ConfigShadeUtils.java:231

            transforms.forEach(
                    transform -> {
                        for (String sensitiveOption : sensitiveOptions) {
                            transform.computeIfPresent(sensitiveOption, processFunction);
                        }
                    });
            configMap.put(Constants.SOURCE, sources);
            configMap.put(Constants.SINK, sinks);
            configMap.put(Constants.TRANSFORM, transforms);
            return ConfigFactory.parseMap(configMap);
        } catch (Exception e) {
            // Log desensitized error information
            log.error(
                    "Failed to {} config with identifier: {}",
                    isDecrypted ? "decrypt" : "encrypt",
                    identifier,
                    e);
            // Rethrow exception without sensitive information
            throw new IllegalArgumentException(
                    String.format(
                            "Failed to %s config. Please check your configuration.",
                            isDecrypted ? "decrypt" : "encrypt"),
                    e);
        }
    }

    public static Set<String> getSensitiveOptions(Config config) {
        Set<String> sensitiveOptions =
                new HashSet<>(
                        TypesafeConfigUtils.getConfig(
                                config != null && config.hasPath(Constants.ENV)
                                        ? config.getConfig(Constants.ENV)
                                        : ConfigFactory.empty(),
                                SHADE_OPTIONS_OPTION,
                                new ArrayList<>()));
        sensitiveOptions.addAll(Arrays.asList(DEFAULT_SENSITIVE_KEYWORDS));
        return sensitiveOptions;

View on GitHub (pinned to cf67b549a7)