Throwable error from subscription stream rethrown as…

Error message

Throwable error from subscription stream rethrown as unchecked

What it means

In GraphqlSubscriptionClient's iterator, hasNext() pulls the next pending item; if the subscription stream emitted a Throwable, it is rethrown as an unchecked exception (asUnchecked) after resetting pending to DONE. GraphQL subscription errors (server-side execution errors, transport failures) surface to the consumer at iteration time rather than at subscribe time.

Solutions

Inspect the rethrown exception (and its cause) for the GraphQL error details from the server.
Wrap subscription iteration in try/catch and implement resubscribe/reconnect logic with backoff.
Fix the subscription query/resolver errors reported by the server payload.
Handle auth token refresh before re-establishing long-lived subscriptions.

Example fix

// before
while (iterator.hasNext()) { process(iterator.next()); }
// after
try {
  while (iterator.hasNext()) { process(iterator.next()); }
} catch (RuntimeException e) {
  log.error("subscription failed", e);
  resubscribeWithBackoff();
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
  while (iterator.hasNext()) {
    handle(iterator.next());
  }
} catch (RuntimeException e) {
  // stream completed with Throwable; inspect cause and resubscribe
  resubscribeWithBackoff();
}

Prevention

Always wrap subscription iteration in try/catch and implement automatic resubscribe with backoff
Refresh auth credentials before long-lived subscriptions expire
Log GraphQL server error payloads from the stream
Validate the subscription query against the schema before subscribing

When it happens

Trigger: Iterating a GraphQL subscription (hasNext()/next() or for-each) after the stream completed with an error: server sent an error payload, the WebSocket/data transport failed, or the client errored during message handling.

Common situations: GraphQL resolvers throwing on the server mid-subscription; WebSocket disconnect during a long-lived subscription; authentication expiring while subscribed; invalid subscription query rejected after initial accept.

Related errors

AI-assisted analysis of OpenFeign/feign@e2a1e27560 (2026-09-10). Data as JSON: /api/errors/fc07033ff54f28b7. Report an issue: GitHub.

Appendix: source

Thrown at graphql/src/main/java/feign/graphql/GraphqlSubscriptionClient.java:456

    private final class PayloadIterator implements Iterator<Map<String, Object>> {

      private final long timeoutMillis;

      private Object pending;

      PayloadIterator(long timeoutMillis) {
        this.timeoutMillis = timeoutMillis;
      }

      @SuppressWarnings("unchecked")
      @Override
      public boolean hasNext() {
        if (pending == null) {
          pending = take();
        }
        if (pending instanceof Throwable error) {
          pending = DONE;
          throw asUnchecked(error);
        }
        return pending != DONE;
      }

      @SuppressWarnings("unchecked")
      @Override
      public Map<String, Object> next() {
        if (!hasNext()) {
          throw new NoSuchElementException();
        }
        var payload = (Map<String, Object>) pending;
        pending = null;
        return payload;
      }

      private Object take() {
        try {
          var event =

View on GitHub (pinned to e2a1e27560)