apache/beam · error · UserCodeTimeoutException

Timeout {timeout} exceeded while completing request: {reques

Error message

Timeout {timeout} exceeded while completing request: {request}

What it means

RequestResponseIO's _execute_request raises UserCodeTimeoutException when the user call completes via a future that hits the configured timeout (concurrent.futures.TimeoutError). The timeout metric is incremented and the original request is included in the message.

Source

Thrown at sdks/python/apache_beam/io/requestresponse.py:205

def _execute_request(
    caller: Caller[RequestT, ResponseT],
    request: RequestT,
    timeout: float,
    metrics_collector: Optional[_MetricsCollector] = None) -> ResponseT:
  with concurrent.futures.ThreadPoolExecutor() as executor:
    future = executor.submit(caller, request)
    try:
      return future.result(timeout=timeout)
    except TooManyRequests as e:
      _LOGGER.info(
          'request could not be completed. got code %i from the service.',
          e.code)
      raise e
    except concurrent.futures.TimeoutError:
      if metrics_collector:
        metrics_collector.timeout_requests.inc(1)
      raise UserCodeTimeoutException(
          f'Timeout {timeout} exceeded '
          f'while completing request: {request}')
    except RuntimeError:
      if metrics_collector:
        metrics_collector.failures.inc(1)
      raise UserCodeExecutionException('could not complete request')


class ExponentialBackOffRepeater(Repeater):
  """Configure exponential backoff retry strategy.

  It retries for exceptions due to the remote service such as
  TooManyRequests (HTTP 429), UserCodeTimeoutException, UserCodeQuotaException.

  It utilizes the decorator
  :func:`apache_beam.utils.retry.with_exponential_backoff`.
  """
  def __init__(self):

View on GitHub (pinned to 12126d8942)

Solutions

1. Increase the timeout via a custom Repeater / timeout parameter passed to RequestResponseIO.
2. Add an internal timeout and fast-fail behavior in the user callable so it returns an error instead of hanging.
3. Verify the remote service health/latency; add retry with exponential backoff (ExponentialBackOffRepeater) for transient slowness.
4. Optimize or batch the request if it is inherently slow.

Example fix

// before
RequestResponseIO(caller, timeout=2)
// after
RequestResponseIO(caller, timeout=30, repeater=ExponentialBackOffRepeater(retries=3))

import time
def within_timeout(last_duration, timeout):
  return last_duration is None or last_duration < timeout

try:
  result = do_request(request)
except UserCodeTimeoutException as e:
  logging.warning('request timed out: %s', e)
  # retry with backoff or fail the element

When it happens

Trigger: Calling RequestResponseIO with a CallTimeoutExceededException-configured timeout where the user's callable or the remote service takes longer than `timeout` seconds; slow or hanging HTTP calls to the remote API.

Common situations: Remote service latency spikes; user-supplied callable doing blocking I/O without its own timeout; timeout configured too low for normal request duration.

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.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• PubSub publish timeout exceeded {self.FLUSH_TIMEOUT_SECS} se
• could not complete request
• Timeout waiting to acquire model: {tag} after {wait_time_ela
• Request to %s failed with status %d: %s
• 'timeout' must be a non-negative number

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