apache/seatunnel · error · ConfigCheckException

System placeholders cannot be used. Incorrect config…

Error message

System placeholders cannot be used. Incorrect config parameter: 

What it means

ConfigBuilder.backfillUserVariables parses user-supplied -D style variable pairs and throws ConfigCheckException when a key is one of SeaTunnel's reserved system placeholders (e.g. table/schema related system variables). System placeholders are managed internally and cannot be overridden by users.

Solutions

1. Rename the user variable to a non-reserved name and update its usage in the config
2. Check TablePlaceholder for the list of reserved system placeholder names
3. Remove the offending variable if it duplicates a value SeaTunnel supplies automatically

Example fix

// before
seatunnel.sh --config job.conf -i table_name=mytable
// after
seatunnel.sh --config job.conf -i src_table_name=mytable  # and use ${src_table_name} in job.conf

if (TablePlaceholder.isSystemPlaceholder(key)) throw new IllegalArgumentException("Reserved placeholder: " + key);

try { ConfigBuilder.of(args); } catch (ConfigCheckException e) { log.error("Variable rejected: {}", e.getMessage()); }

When it happens

Trigger: Launching a job with variables like `--variable table_name=...` or -D key=value where key matches TablePlaceholder.isSystemPlaceholder, e.g. using reserved table placeholder names as custom variable names.

Common situations: Users name a custom variable the same as a built-in system placeholder, or copy example commands that accidentally use reserved keys.

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

• At least one sink plugin must be configured.
• At least one source plugin must be configured.
• AzureCosmosDB requires uri, endpoint, or connection string…
• Cannot specify both ' ' and root-level ' '.
• checkResult.getMsg()

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

Appendix: source

Thrown at seatunnel-core/seatunnel-core-starter/src/main/java/org/apache/seatunnel/core/starter/utils/ConfigBuilder.java:261

            throw e;
        } catch (Exception warn) {
            log.warn(
                    "Loading config failed with spi {}, fallback to HOCON loader.",
                    configAdapter.getClass().getName());
            return ofInner(filePath, variables);
        }
    }

    private static Config backfillUserVariables(Config config, List<String> variables) {
        if (variables != null) {
            variables.stream()
                    .filter(Objects::nonNull)
                    .map(variable -> variable.split("=", 2))
                    .filter(pair -> pair.length == 2)
                    .peek(
                            pair -> {
                                if (TablePlaceholder.isSystemPlaceholder(pair[0])) {
                                    throw new ConfigCheckException(
                                            "System placeholders cannot be used. Incorrect config parameter: "
                                                    + pair[0]);
                                }
                            })
                    .forEach(pair -> System.setProperty(pair[0], pair[1]));
            Config systemConfig =
                    Parseable.newProperties(
                                    System.getProperties(),
                                    ConfigParseOptions.defaults()
                                            .setOriginDescription("system properties"))
                            .parse()
                            .toConfig();

            Config resolvedConfig =
                    config.resolveWith(
                            systemConfig, ConfigResolveOptions.defaults().setAllowUnresolved(true));

            Map<String, Object> configMap = resolvedConfig.root().unwrapped();

View on GitHub (pinned to cf67b549a7)