apache/seatunnel · error · IllegalArgumentException

transport.token is required.

Error message

transport.token is required.

What it means

EdgeTransportConfig requires a non-blank transport.token for authentication. After validating the auth type, the constructor reads the optional TOKEN option and throws this IllegalArgumentException if it is absent or whitespace-only, because the agent cannot authenticate without a token.

Source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-transport/src/main/java/org/apache/seatunnel/edge/agent/transport/config/EdgeTransportConfig.java:59

    private final long initialBackoffMs;
    private final long maxBackoffMs;
    private final int maxReconnectCycles;

    public EdgeTransportConfig(ReadonlyConfig config) {
        Objects.requireNonNull(config, "config");
        String rawEndpoint = config.get(EdgeTransportOptions.ENDPOINT);
        if (rawEndpoint == null || rawEndpoint.trim().isEmpty()) {
            throw new IllegalArgumentException("transport.endpoint is required.");
        }
        String trimmedEndpoint = rawEndpoint.trim();
        EdgeTransportEndpoints.validateFormat(trimmedEndpoint);
        this.endpoint = trimmedEndpoint;

        String authType = config.get(EdgeTransportOptions.AUTH_TYPE);
        validateAuthType(authType);
        String rawToken = config.getOptional(EdgeTransportOptions.TOKEN).orElse(null);
        if (rawToken == null || rawToken.trim().isEmpty()) {
            throw new IllegalArgumentException("transport.token is required.");
        }
        this.token = rawToken.trim();

        EdgePacketMode.from(config.get(EdgeTransportOptions.PACKET_MODE));
        EdgePacketCompressionType.from(config.get(EdgeTransportOptions.COMPRESSION));
        EdgePacketEncryptionType encryption =
                EdgePacketEncryptionType.from(config.get(EdgeTransportOptions.ENCRYPTION));
        if (encryption == EdgePacketEncryptionType.AES_GCM) {
            String key =
                    config.getOptional(EdgeTransportOptions.AES_SECRET_KEY_BASE64).orElse(null);
            if (key == null || key.trim().isEmpty()) {
                throw new IllegalArgumentException(
                        "transport.aes-secret-key-base64 is required when transport.encryption"
                                + " is \"aes_gcm\".");
            }
        }

        this.connectTimeoutMs = config.get(EdgeTransportOptions.CONNECT_TIMEOUT_MS);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set transport.token in the agent config to the credential issued by the server, e.g. transport:\n token: <secret>.
2. Verify secret injection (env vars, mounted secret files) actually populated the token in the deployed config.
3. Check that template placeholders like ${TOKEN} are resolved and not left empty at deploy time.
4. Confirm the token is trimmed/non-blank — whitespace-only values are rejected the same as missing ones.

Example fix

// before
transport:
  endpoint: 10.0.0.5:9090
  token: ""
// after
transport:
  endpoint: 10.0.0.5:9090
  token: ${AGENT_TOKEN}

String tok = config.get(EdgeTransportOptions.TOKEN); if (tok == null || tok.trim().isEmpty()) { throw new IllegalArgumentException("transport.token must be set before building EdgeTransportConfig"); }

boolean hasToken(org.apache.seatunnel.shade.com.typesafe.config.ReadonlyConfig c) { return c.getOptional(EdgeTransportOptions.TOKEN).map(t -> !t.trim().isEmpty()).orElse(false); }

try { new EdgeTransportConfig(config); } catch (IllegalArgumentException e) { if (e.getMessage().equals("transport.token is required.")) { log.error("transport.token missing or blank; check secret injection"); } throw e; }

When it happens

Trigger: Constructing new EdgeTransportConfig(config) where transport.token is missing, empty, or only whitespace in the ReadonlyConfig, regardless of the configured auth type.

Common situations: Deploying with a config template where the token placeholder was never replaced; secrets not injected into the container/environment; token key removed during config refactoring; blank token passed via an empty environment variable interpolation.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• transport.endpoint is required.
• Option '${valuesAndOptions[index + 1]}' is not valid for the
• AzureCosmosDB requires key, primary_key, secondary_key, or a
• Invalid user/password specified
• The GCS service_account_key_file option must not be blank

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