apache/seatunnel · info · IllegalStateException

UTF-8 encoding is not available

Error message

UTF-8 encoding is not available

What it means

PostHogSourceParameter.encodePathSegment() URL-encodes path segments using URLEncoder.encode(value, "UTF-8"). UTF-8 is required by the JVM spec to exist, but the API declares UnsupportedEncodingException; if it were ever thrown (broken JVM charset setup), the connector rethrows it as IllegalStateException('UTF-8 encoding is not available').

Source

Thrown at seatunnel-connectors-v2/connector-http/connector-http-posthog/src/main/java/org/apache/seatunnel/connectors/seatunnel/posthog/source/config/PostHogSourceParameter.java:94

        setSocketTimeoutMs(pluginConfig.get(HttpSourceOptions.SOCKET_TIMEOUT_MS));
    }

    private static String normalizeBaseUrl(String baseUrl) {
        String normalized = requireNonBlank(baseUrl, "base_url");
        while (normalized.endsWith("/")) {
            normalized = normalized.substring(0, normalized.length() - 1);
        }
        if (normalized.isEmpty()) {
            throw new IllegalArgumentException("PostHog option 'base_url' must not be blank");
        }
        return normalized;
    }

    private static String encodePathSegment(String value) {
        try {
            return URLEncoder.encode(value, "UTF-8").replace("+", "%20");
        } catch (UnsupportedEncodingException e) {
            throw new IllegalStateException("UTF-8 encoding is not available", e);
        }
    }

    private static void setHeader(Map<String, String> headers, String name, String value) {
        headers.keySet().removeIf(headerName -> headerName.equalsIgnoreCase(name));
        headers.put(name, value);
    }

    private static String requireNonBlank(String value, String optionName) {
        if (value == null || value.trim().isEmpty()) {
            throw new IllegalArgumentException(
                    "PostHog option '" + optionName + "' must not be blank");
        }
        return value.trim();
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Run SeaTunnel on a standard JDK/JRE (8+) where UTF-8 is guaranteed.
  2. Verify the JVM's supported charsets (java.nio.charset.Charset.availableCharsets() contains UTF-8).
  3. Rebuild the runtime image with a complete JDK if using a stripped JRE.
  4. If it persists, report an upstream issue since this signals a JVM installation problem, not a config problem.
Defensive patterns

Strategy: try-catch

Validate before calling

if (!java.nio.charset.Charset.availableCharsets().containsKey("UTF-8")) {
    throw new IllegalStateException("JVM does not support UTF-8; use a standard JDK");
}

Try / catch

try {
    runSeaTunnelJob(config);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("UTF-8 encoding is not available")) {
        log.error("Broken JVM charset setup; switch to a standard JDK 8+ runtime");
    }
    throw e;
}

Prevention

When it happens

Trigger: Running on a JVM where the default charset support is broken/nonstandard (e.g. unusual embedded or stripped-down JRE missing UTF-8 charset provider); practically never occurs on standard HotSpot/OpenJDK runtimes.

Common situations: Custom/minimal JVM builds, exotic platforms, or manipulated java.nio.charset settings in container images.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

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