apache/beam · error · UserCodeExecutionException

could not complete request

Error message

could not complete request

What it means

CallULike's CallableCall adapter submits the user's PTransform call and waits on a Future. After handling timeout/interruption and ExecutionException, if the future completed without an expected result (e.g. completed exceptionally in an unexpected way or returned nothing), it throws UserCodeExecutionException('could not complete request').

Solutions

1. Inspect the cause chain: enable logging around parseAndThrow to see the original ExecutionException cause.
2. Ensure your user PTransform's call() always completes the future with a response or a UserCodeExecutionException.
3. Check that the executor is not shut down / cancelled mid-call (future.cancel races).
4. Add retry with backoff at the RequestResponseIO level for transient failures.

Example fix

// before
// user call completes future without setting a response
// after
responseFuture.complete(processBatch(request)); // always complete or completeExceptionally(new UserCodeExecutionException(e))

// Ensure the user call always completes its future before returning
if (!responseFuture.isDone() && !responseFuture.cancel(false)) { log.warn("future left incomplete"); }

try { response = call.call(request); } catch (UserCodeExecutionException e) { if ("could not complete request".equals(e.getMessage())) { /* retry with backoff, inspect root cause */ } }

When it happens

Trigger: Calling the RequestResponse IO's Call.call where the underlying future finishes without producing a response and without matching the earlier exception branches.

Common situations: User Call implementation completing the future abnormally (e.g. returning null/completing with a cancelled state); executor shutdown races; wrapped exception types not matched by parseAndThrow.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• could not fetch database schema
• Processing of an element in transform
• PubSub publish timeout exceeded
• Timed out waiting for cache file for PCollection
• 'timeout' must be a non-negative number

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/ed411731db7077f9. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/rrio/src/main/java/org/apache/beam/io/requestresponse/Call.java:543

      this.caller = caller;
    }

    private void setExecutor(ExecutorService executor) {
      this.executor = executor;
    }

    @Override
    public ResponseT call(RequestT request) throws UserCodeExecutionException {
      Future<ResponseT> future = checkStateNotNull(executor).submit(() -> caller.call(request));
      try {
        return future.get(timeout.getMillis(), TimeUnit.MILLISECONDS);
      } catch (TimeoutException | InterruptedException e) {
        future.cancel(true);
        throw new UserCodeTimeoutException(e);
      } catch (ExecutionException e) {
        parseAndThrow(future, e);
      }
      throw new UserCodeExecutionException("could not complete request");
    }
  }

  private static class SetupTeardownWithTimeout implements SetupTeardown {
    private final Duration timeout;
    private final SetupTeardown setupTeardown;
    private @MonotonicNonNull ExecutorService executor;

    SetupTeardownWithTimeout(Duration timeout, SetupTeardown setupTeardown) {
      this.timeout = timeout;
      this.setupTeardown = setupTeardown;
    }

    private void setExecutor(ExecutorService executor) {
      this.executor = executor;
    }

    @Override

View on GitHub (pinned to 12126d8942)