apache/seatunnel · error · GraphQLConnectorException

PROTOCOL_ERROR

PROTOCOL_ERROR

Error message

For non-subscription mode, URL must start with http:// or https://

What it means

GraphQLUtil.checkProtocol validates the configured URL scheme before building a reader/writer. In non-subscription mode the URL must start with http:// or https://; otherwise GraphQLConnectorException(PROTOCOL_ERROR) is thrown with this message.

Source

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

    private static final Option[] DEFAULT_OPTIONS = {
        Option.SUPPRESS_EXCEPTIONS, Option.DEFAULT_PATH_LEAF_TO_NULL
    };

    private static final Configuration jsonConfiguration =
            Configuration.defaultConfiguration().addOptions(DEFAULT_OPTIONS);

    private static void checkHttpProtocol(String url) {
        checkProtocol(
                url,
                "http://",
                "https://",
                "For non-subscription mode, URL must start with http:// or https://");
    }

    private static void checkProtocol(
            String url, String prefix, String prefix1, String errorMessage) {
        if (!url.startsWith(prefix) && !url.startsWith(prefix1)) {
            throw new GraphQLConnectorException(
                    GraphQLConnectorErrorCode.PROTOCOL_ERROR, errorMessage);
        }
    }

    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);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set url to an http:// or https:// endpoint for non-subscription mode
2. If you intended a websocket endpoint, enable subscription mode in source config
3. Add the scheme prefix if you omitted it (https://host/graphql)
4. Fix typos in the scheme

Example fix

// before
url = "myserver/graphql"
// after
url = "https://myserver/graphql"

function checkUrl(u) { return u.startsWith('http://') || u.startsWith('https://'); }  // for non-subscription mode

function isHttpUrl(String u) { return u != null && (u.startsWith("http://") || u.startsWith("https://")); }

try { GraphQLUtil.checkHttpProtocol(url); } catch (GraphQLConnectorException e) { url = "https://" + stripScheme(url); }

When it happens

Trigger: checkHttpProtocol or checkWebSocketProtocol receives a URL lacking the required prefix, e.g. a ws:// URL passed while subscription (enableSubscription) is false.

Common situations: User configured a ws:// or wss:// endpoint but did not set subscription mode; URL missing scheme entirely ("myserver/graphql"); typos like htp://.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• GRAPHQL_SOURCE_PARAMETER_ERROR
• GRAPHQL_SINK_PARAMETER_ERROR
• Invalid plugin dependency path: ${uri}
• Table URL cannot be null or empty
• Invalid table URL format: '%s'. Expected format: http://host

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