apache/seatunnel · error · GraphQLConnectorException

GRAPHQL_SOURCE_PARAMETER_ERROR

GRAPHQL_SOURCE_PARAMETER_ERROR

Error message

GraphQL Sink query is required.

What it means

validateSinkOperation requires a non-empty GraphQL query string for the sink; if null or empty it throws GRAPHQL_SOURCE_PARAMETER_ERROR with "GraphQL Sink query is required.". The sink needs an explicit mutation document to execute per batch.

Source

Thrown at seatunnel-connectors-v2/connector-graphql/src/main/java/org/apache/seatunnel/connectors/seatunnel/graphql/util/GraphQLUtil.java:83

    private static void checkWebSocketProtocol(String url) {
        checkProtocol(
                url,
                "ws://",
                "wss://",
                "For subscription mode, URL must start with ws:// or wss://");
    }

    public static OperationDefinition.Operation parseOperationType(String query) {
        Document document = new Parser().parseDocument(query);
        return document.getDefinitionsOfType(OperationDefinition.class).stream()
                .findFirst()
                .map(OperationDefinition::getOperation)
                .orElse(null);
    }

    public static void validateSinkOperation(String query) {
        if (query == null || query.isEmpty()) {
            throw new GraphQLConnectorException(
                    GraphQLConnectorErrorCode.GRAPHQL_SOURCE_PARAMETER_ERROR,
                    "GraphQL Sink query is required.");
        }
        OperationDefinition.Operation operationType = parseOperationType(query);
        switch (operationType) {
            case MUTATION:
                break;
            case SUBSCRIPTION:
            case QUERY:
            default:
                throw new GraphQLConnectorException(
                        GraphQLConnectorErrorCode.GRAPHQL_SINK_PARAMETER_ERROR,
                        "GraphQL Sink unsupported operation type: " + operationType);
        }
    }

    public static void validateSourceOperation(String query, Boolean enableSubscription) {
        if (query == null) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add the query option with a mutation document to the sink config
2. Check for typos in the config key
3. Ensure the value is not an empty string
4. Confirm the document parses and is a MUTATION (next validation step)

Example fix

// before
GraphQLSink {
  url = "https://api.example.com/graphql"
}
// after
GraphQLSink {
  url = "https://api.example.com/graphql"
  query = "mutation ($name: String!) { createUser(name: $name) { id } }"
}

if (query == null || query.isEmpty()) throw new IllegalArgumentException("GraphQL sink query required");  // pre-check before submit

boolean hasSinkQuery = cfg.getOptional("query").map(q -> !q.isEmpty()).orElse(false);

try { GraphQLUtil.validateSinkOperation(query); } catch (GraphQLConnectorException e) { /* surface which option is missing */ }

When it happens

Trigger: GraphQL sink created with the query/operation option missing or set to an empty string; validateSinkOperation called during sink initialization.

Common situations: Forgot the query option in sink config; config key typo so the option falls back to null; template rendering produced an empty string.

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

• GRAPHQL_SINK_PARAMETER_ERROR
• Option 'field_delimiter' cannot be empty
• Option 'max_in_flight' must be greater than zero
• Option 'operation_timeout_ms' must be greater than zero
• Options 'credentials_path' and 'emulator_host' cannot be con

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