apache/beam · error · RuntimeException

RuntimeException

Error message

RuntimeException

What it means

When creating a unix domain socket address, SocketAddressFactory tries to create the underlying socket file eagerly (to register delete-on-exit). If File.createNewFile() fails with an IOException — e.g. missing directory, no write permission — it is wrapped in a RuntimeException.

Source

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

  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);
      return new InetSocketAddress(hostAndPort.getHost(), hostAndPort.getPort());
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the socket's parent directory exists and is writable by the process user (mkdir/chmod it).
2. Choose a writable absolute path such as /tmp/beam-<id>.sock for the unix socket endpoint.
3. Use a TCP endpoint instead if the filesystem is read-only or shared across containers.

Example fix

// before
--endpoint=unix:/var/run/beam.sock // /var/run not writable in container
// after
mkdir -p /tmp/beam-sockets
--endpoint=unix:/tmp/beam-sockets/beam.sock

File f = new File(socketPath);
if (!f.getParentFile().exists() || !f.getParentFile().canWrite())
  throw new IllegalStateException("socket dir missing/unwritable: " + f.getParent());

try { addr = SocketAddressFactory.createFrom(endpoint); } catch (RuntimeException e) { /* inspect IOException cause: fix permissions or switch to TCP */ throw e; }

When it happens

Trigger: Configuring a unix socket endpoint whose parent directory does not exist or is not writable by the process (commonly the SDK harness or job server user in a container).

Common situations: Read-only container filesystems, non-root users lacking permission to /tmp or the configured socket directory, socket directory deleted between processes.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• File path must be absolute:
• Unable to encode constant members of ParamWindowedValueCoder
• Unable to decode constant members from payload for ParamWind
• Error creating JMS session
• Error creating JMS consumer

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