apache/seatunnel · error · GraphQLConnectorException

GRAPHQL_SINK_PARAMETER_ERROR

GRAPHQL_SINK_PARAMETER_ERROR

Error message

GraphQL Sink unsupported operation type: ${operationType}

What it means

After parsing the sink query's operation type, validateSinkOperation only allows MUTATION. QUERY, SUBSCRIPTION, or unrecognized operations throw GRAPHQL_SINK_PARAMETER_ERROR with the offending type. Sinks write data, so only mutations are valid.

Source

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

                .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) {
            throw new GraphQLConnectorException(
                    GraphQLConnectorErrorCode.GRAPHQL_SOURCE_PARAMETER_ERROR,
                    "GraphQL Source is required.");
        }
        OperationDefinition.Operation operationType;
        try {
            operationType = parseOperationType(query);
        } catch (Exception e) {
            throw new GraphQLConnectorException(
                    GraphQLConnectorErrorCode.GRAPHQL_SOURCE_PARAMETER_ERROR,
                    "Failed to parse operation type from query: " + e.getMessage());

View on GitHub (pinned to cf67b549a7)

Solutions

1. Change the sink query to start with the 'mutation' keyword
2. Remove the query/subscription document and write a proper mutation
3. Verify with: parseOperationType or running the query in GraphiQL
4. Keep source queries in the source config and mutations in the sink config

Example fix

// before
query = "query { users { id name } }"
// after
query = "mutation ($name: String!) { createUser(name: $name) { id } }"

// check operation keyword before configuring sink
if (!query.trim().startsWith("mutation")) throw new IllegalArgumentException("sink query must be a mutation");

boolean isMutation = query != null && query.trim().toLowerCase().startsWith("mutation");

try { GraphQLUtil.validateSinkOperation(query); } catch (GraphQLConnectorException e) { log.error("sink query must be a mutation, got: {}", e.getMessage()); }

When it happens

Trigger: The configured sink query's root operation is a query or subscription, e.g. user pasted a source query into the sink, or the document has no explicit operation keyword so parsing yields a default/unexpected type.

Common situations: Copy-pasting the source query into the sink config; writing a document without an explicit 'mutation' keyword; anonymous query documents.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• GRAPHQL_SOURCE_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/92507b3d59204937. Report an issue: GitHub.