apache/beam · error · Error

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

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.

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)

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.