apache/beam · error · Error

Timed out waiting for service after

Error message

Timed out waiting for service after ${timeoutMs}ms.

What it means

portReady polls the service's TCP port until timeoutMs elapses. If the process is still alive but the port never accepts a connection within the timeout, the launcher gives up and throws. The service is presumably starting too slowly or failed to bind its port while remaining alive.

Solutions

Increase the timeout (pass a larger timeoutMs to start()/service options).
Verify the service's host/port configuration matches what the SDK polls.
Check service logs for binding errors or slow startup warnings.
Pre-warm/reuse the service instead of restarting per pipeline.

Example fix

// before
await service.start({timeoutMs: 5000});

// after
await service.start({timeoutMs: 60000});

Defensive patterns

Strategy: retry

Validate before calling

// confirm the endpoint is bindable/reachable before start
await checkHostResolves(host);
await checkPortFree(host, port);

Try / catch

let started;
for (const timeoutMs of [10000, 30000, 60000]) {
  try { started = await service.start({timeoutMs}); break; }
  catch (e) {
    if (!/Timed out waiting for service/.test(String(e))) throw e;
  }
}

Prevention

Set generous timeouts on slow or resource-limited machines.
Ensure host/port configuration matches where the service actually binds.
Reuse long-lived expansion services instead of cold-starting per run.

When it happens

Trigger: Starting a Java/Python expansion or job service on a slow machine or under heavy load; service bound to a different host than the one polled; timeoutMs set too low in start().

Common situations: First run of a large fat-jar with cold JIT/class loading; container resource limits slowing startup; service misconfigured to listen on localhost vs a container hostname.

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

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

Appendix: source

Thrown at sdks/typescript/src/apache_beam/utils/service.ts:196

      }
      await new Promise((r) => setTimeout(r, iterMs));
      try {
        await new Promise<void>((resolve, reject) => {
          const socket = net.createConnection(port, host, () => {
            connected = true;
            socket.end();
            resolve();
          });
          socket.on("error", (err) => {
            reject(err);
          });
        });
      } catch (err) {
        // go around again
      }
    }
    if (!connected) {
      throw new Error(
        "Timed out waiting for service after " + timeoutMs + "ms.",
      );
    }
  }
}

export function serviceProviderFromJavaGradleTarget(
  gradleTarget: string,
  args: string[] | undefined = undefined,
): () => Promise<Service> {
  return async () => {
    let jar: string;
    const serviceInfo = serviceOverrideFor(gradleTarget);
    if (serviceInfo) {
      if (serviceInfo.match(/^[a-zA-Z0-9.]+:[0-9]+$/)) {
        return new ExternalService(serviceInfo);
      } else {
        jar = serviceInfo;

View on GitHub (pinned to 12126d8942)