apache/beam · error · IllegalArgumentException

File path must be absolute:

Error message

File path must be absolute: 

What it means

SocketAddressFactory.createFrom parses an endpoint string; values prefixed with the unix domain socket prefix must name an absolute file path, since domain sockets live in the filesystem. A relative path is ambiguous across processes and is rejected with IllegalArgumentException.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/fn/channel/SocketAddressFactory.java:41

import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.SocketAddress;
import org.apache.beam.vendor.grpc.v1p69p0.io.netty.channel.unix.DomainSocketAddress;
import org.apache.beam.vendor.guava.v32_1_2_jre.com.google.common.net.HostAndPort;

/** Creates a {@link SocketAddress} based upon a supplied string. */
public class SocketAddressFactory {
  private static final String UNIX_DOMAIN_SOCKET_PREFIX = "unix://";

  /** Parse a {@link SocketAddress} from the given string. */
  public static SocketAddress createFrom(String value) {
    if (value.startsWith(UNIX_DOMAIN_SOCKET_PREFIX)) {
      // Unix Domain Socket address.
      // Create the underlying file for the Unix Domain Socket.
      String filePath = value.substring(UNIX_DOMAIN_SOCKET_PREFIX.length());
      File file = new File(filePath);
      if (!file.isAbsolute()) {
        throw new IllegalArgumentException("File path must be absolute: " + filePath);
      }
      try {
        if (file.createNewFile()) {
          // If this application created the file, delete it when the application exits.
          file.deleteOnExit();
        }
      } catch (IOException ex) {
        throw new RuntimeException(ex);
      }
      // Create the SocketAddress referencing the file.
      return new DomainSocketAddress(file);
    } else {
      // Standard TCP/IP address.
      HostAndPort hostAndPort = HostAndPort.fromString(value);
      checkArgument(
          hostAndPort.hasPort(),
          "Address must be a unix:// path or be in the form host:port. Got: %s",
          value);

View on GitHub (pinned to 12126d8942)

Solutions

1. Use an absolute path in the unix socket endpoint, e.g. "unix:/tmp/beam-socket".
2. Start the job server and SDK harness with consistent working directories or explicit absolute socket paths.
3. Alternatively switch the endpoint to a TCP address like "host:port" to avoid filesystem path issues.

Example fix

// before
--endpoint=unix:beam.sock
// after
--endpoint=unix:/tmp/beam.sock

String path = endpoint.replaceFirst("^unix:", "");
if (!new File(path).isAbsolute()) throw new IllegalArgumentException("unix socket path must be absolute: " + path);

When it happens

Trigger: Passing an endpoint like "unix:relative.sock" (path not starting with /) to Beam fn API channel/server configuration, e.g. via --endpoint or ApiServiceDescriptor URLs.

Common situations: Runner/container misconfiguration where the unix socket directory is omitted or configured with a relative path; job server started from a different working directory than the SDK harness.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unrecognized value for stable unique names:
• RuntimeException
• Secret option string cannot be null
• Secret string must contain a valid type parameter
• Invalid secret type %s, currently supported types: %s

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