apache/seatunnel · error · IllegalArgumentException

provided string configuration is null or empty! Please use a

Error message

provided string configuration is null or empty! Please use a well-structured content.

What it means

ConfigProvider.locateAndGetSeaTunnelConfigFromString builds a SeaTunnelConfig from an inline config string. It rejects null, empty, or whitespace-only input up front with IllegalArgumentException because there is nothing to parse.

Source

Thrown at seatunnel-engine/seatunnel-engine-common/src/main/java/org/apache/seatunnel/engine/common/config/ConfigProvider.java:86

            // 3. Loading the default YAML configuration file
            yamlConfigLocator.locateDefault();
            config =
                    new YamlSeaTunnelConfigBuilder(yamlConfigLocator)
                            .setProperties(properties)
                            .build();
        }
        return config;
    }

    public static SeaTunnelConfig locateAndGetSeaTunnelConfigFromString(String source) {
        return locateAndGetSeaTunnelConfigFromString(source, null);
    }

    @NonNull public static SeaTunnelConfig locateAndGetSeaTunnelConfigFromString(
            String source, Properties properties) {
        SeaTunnelConfig config;
        if (isNullOrEmptyAfterTrim(source)) {
            throw new IllegalArgumentException(
                    "provided string configuration is null or empty! "
                            + "Please use a well-structured content.");
        }
        byte[] bytes = source.getBytes();
        // Try loading YAML config from the source Text String
        config =
                new YamlSeaTunnelConfigBuilder(new ByteArrayInputStream(bytes))
                        .setProperties(properties)
                        .build();
        return config;
    }

    @NonNull public static ClientConfig locateAndGetClientConfig() {
        validateSuffixInSystemProperty(SYSPROP_CLIENT_CONFIG);

        ClientConfig config;
        YamlClientConfigLocator yamlConfigLocator = new YamlClientConfigLocator();

View on GitHub (pinned to cf67b549a7)

Solutions

Load the config content correctly and assert it is non-empty before calling the API.
Fix the upstream source (env var, secret, template) so it contains actual config text.
Fall back to file-based locateAndGetSeaTunnelConfig() when the inline source is blank.

Example fix

// before
SeaTunnelConfig cfg = ConfigProvider.locateAndGetSeaTunnelConfigFromString(configString, props);
// after
if (configString == null || configString.trim().isEmpty()) {
    throw new IllegalStateException("config content missing from source");
}
SeaTunnelConfig cfg = ConfigProvider.locateAndGetSeaTunnelConfigFromString(configString, props);

Defensive patterns

Strategy: validation

Validate before calling

if (source == null || source.trim().isEmpty()) {
    throw new IllegalArgumentException("inline config content is empty; check file/env source");
}

Try / catch

try {
    return ConfigProvider.locateAndGetSeaTunnelConfigFromString(source, props);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("null or empty")) {
        return ConfigProvider.locateAndGetSeaTunnelConfig();
    }
    throw e;
}

Prevention

Assert config content non-empty right after loading it.
Log the source name (path/env var) when the string is empty.
Prefer file-based config lookup unless inline content is required.

When it happens

Trigger: Calling locateAndGetSeaTunnelConfigFromString(source, properties) with source == null, "", or whitespace-only.

Common situations: File-reading helper silently returning empty on a missing file; unset environment variable or secret holding the config; template substitution producing an empty string.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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