quarkusio/quarkus · error · IllegalArgumentException

Directive 'skip' was not found in the query (on the server s

Error message

Directive 'skip' was not found in the query (on the server side).

What it means

This GraphQL server-side query resolver requires the @skip directive to be present on the field being fetched. It reads QueryDirectives from the DataFetchingEnvironment; when getImmediateAppliedDirective("skip") returns empty the resolver throws IllegalArgumentException, meaning the client sent a query without the expected @skip directive.

Source

Thrown at integration-tests/smallrye-graphql-client/src/main/java/io/quarkus/io/smallrye/graphql/client/LuckyNumbersResource.java:59

    public Multi<Integer> primeNumbers() {
        return Multi.createFrom().items(2, 3, 5, 7, 11, 13);
    }

    @Query(value = "echoList")
    public List<Integer> echoList(@NonNull List<Integer> list) {
        return list;
    }

    @Query
    public String returnHeader(String key) {
        return request.getCurrent().request().getHeader(key);
    }

    @Query
    public String piNumber() {
        QueryDirectives directives = context.getDataFetchingEnvironment().getQueryDirectives();
        if (directives.getImmediateAppliedDirective("skip").isEmpty()) {
            throw new IllegalArgumentException("Directive 'skip' was not found in the query (on the server side).");
        }

        return "3.14159";
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

Include @skip in the query sent to the server, e.g. `piNumber @skip(if: false)`
Use the SmallRye GraphQL client query/document builder to add the directive instead of hand-writing the query
Relax the server check if the directive is optional in your API contract

Example fix

// before
String query = "{ piNumber }";
// after
String query = "{ piNumber @skip(if: false) }";

Defensive patterns

Strategy: validation

Validate before calling

String query = "{ piNumber @skip(if: false) }";
// verify directive presence in tests before asserting on the result

Try / catch

try {
    String pi = client.piNumber();
} catch (GraphQLClientException e) {
    if (e.getMessage().contains("Directive 'skip' was not found")) {
        // fix the query document to include @skip
    }
}

Prevention

Always build client queries from the server schema/directive definitions
Add a contract test that asserts required directives are present in sent queries
Check server logs for QueryDirectives resolution issues after client query changes

When it happens

Trigger: Querying piNumber without an inline @skip directive on the field, e.g. `{ piNumber }` instead of `{ piNumber @skip(if: false) }`.

Common situations: SmallRye GraphQL client integration tests where the client template must include @skip; mismatches after changing the client query and forgetting the directive; older servers not supporting directive introspection.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/5844abd3796c135b. Report an issue: GitHub.