apache/seatunnel · error · IllegalArgumentException

PostHog option '${optionName}' must not be blank

Error message

PostHog option '${optionName}' must not be blank

What it means

PostHogSourceParameter.requireNonBlank() is the shared validation guard for mandatory string options. It throws IllegalArgumentException with the option name embedded in the message when a value is null or whitespace-only. It is called from projectId(), apiKey(), query(), and normalizeBaseUrl(), so this message names whichever PostHog option is missing.

Source

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

        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. Fill in the option named in the message ('project_id', 'api_key', 'query', or 'base_url') with a real non-blank value.
2. For api_key, generate a PostHog personal API key with read access to the target project.
3. For project_id, use the numeric project ID from PostHog project settings, not the project name.
4. Check env-var/placeholder resolution so interpolated values are not empty at runtime.

Example fix

// before
PostHog {
  project_id = ""
  api_key = "${POSTHOG_KEY}"
  query = "SELECT * FROM events"
}

// after
PostHog {
  project_id = "12345"
  api_key = "phx_xxxxxxxxxxxx"
  query = "SELECT * FROM events"
}

for (String key : new String[]{"project_id", "api_key", "query", "base_url"}) {
    String v = config.getString(key);
    if (v == null || v.trim().isEmpty()) {
        throw new IllegalArgumentException("PostHog option '" + key + "' must not be blank");
    }
}

try {
    buildParameter(config);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("PostHog option")) {
        log.error("Missing PostHog config: {}", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: Building PostHogSourceParameter.buildWithConfig with any of project_id, api_key, query, or base_url absent, empty (''), or whitespace-only in the source config.

Common situations: Forgetting to fill required fields in the HOCON config, placeholder values replaced by empty strings, env-var interpolation failing so options resolve to blank, copy-pasting a template without editing values.

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

• PostHog option 'base_url' must not be blank
• Schema config can not be empty
• Unknown format type:
• Option '${option}' cannot be blank
• Option '${valuesAndOptions[index + 1]}' is not valid for the

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