Describe the bug, including details regarding any error messages, version, and platform.

h3. Summary A {{ClassCastException}} occurs when initializing a {{FlightClient}} with Unix Domain Socket (UDS) and Epoll transport in Apache Arrow 16.0.0, 17.0.0, and 18.0.0. This is a regression, as the same code works perfectly in versions 12.0.0 and 15.0.0.

h3. Description When creating a {{FlightClient}} to connect via {{Location.forGrpcUnix(...)}} on Linux with Epoll native transport enabled, the application crashes during initialization. The root cause is an incorrect type cast in the internal Netty/gRPC logic bundled with {{flight-core}}: it attempts to cast the client-side class {{EpollDomainSocketChannel}} to {{ServerChannel}}.

This logic error was introduced between version 15.0.0 and 16.0.0, and persists in all subsequent releases (16, 17, 18).

h3. Affected Versions

• ❌ 18.0.0 (Confirmed Broken)
• ❌ 17.0.0 (Confirmed Broken)
• ❌ 16.0.0 (Confirmed Broken)
• ✅ 15.0.0 (Works Correctly)
• ✅ 12.0.0 (Works Correctly)

h3. Steps to Reproduce

Create a Java project with {{arrow-flight}} dependency set to 16.0.0, 17.0.0, or 18.0.0.

Ensure {{netty-transport-native-epoll}} is on the classpath.

Execute the following code:

{code:java} import org.apache.arrow.flight.FlightClient; import org.apache.arrow.flight.Location;

public class TestUds { public static void main(String[] args) { // Try to create a client using Unix Domain Socket Location location = Location.forGrpcUnix("/tmp/arrow-test.sock");

    // This line triggers the crash in v16/v17/v18
    FlightClient client = FlightClient.builder(location).build();
    
    System.out.println("Client created successfully!");
}

} {code}

Observe the {{ClassCastException}}.

Verification: Change dependency to 15.0.0, re-run, and observe it works without error.

h3. Error Log / Stack Trace {code:java} Exception in thread "main" java.lang.ClassCastException: class io.netty.channel.epoll.EpollDomainSocketChannel cannot be cast to class io.netty.channel.ServerChannel at java.lang.Class.asSubclass(Class.java:3406) at org.apache.arrow.flight.grpc..(.java:) // NOTE: Please replace , , and with actual info from your stack trace if available. // If using shaded jar, the class name might be obfuscated or internal. ... {code}

h3. Root Cause Analysis By decompiling {{flight-core}} jars for versions 16.0.0, 17.0.0, and 18.0.0, the following erroneous code was found in the initialization path: {code:java} // BUG: Incorrectly casting Client Channel to ServerChannel Class<?> clazz = Class.forName("io.netty.channel.epoll.EpollDomainSocketChannel"); clazz.asSubclass(ServerChannel.class); // Fails because EpollDomainSocketChannel implements Channel, not ServerChannel {code}

In versions 12.0.0 and 15.0.0, this logic either did not exist or correctly handled the channel types without cross-casting. It appears a refactoring introduced in v16.0.0 caused this regression, which has not been fixed in later versions.

h3. Environment

• OS: Linux (Ubuntu/CentOS/Alpine)
• Java: OpenJDK 11/17/21
• Netty: 4.1.x (bundled with respective Arrow versions)
• Architecture: x86_64 / aarch64

h3. Workaround

Downgrade: Use Apache Arrow 15.0.0 (or earlier) if UDS is strictly required.

Switch Protocol: Use TCP ({{Location.forGrpcInsecure}}) instead of Unix Domain Sockets in v16/v17/v18.

h3. Impact This breaks any production system relying on FlightClient over Unix Domain Sockets in the latest three major stable releases (16, 17, 18), forcing users to downgrade significantly or switch to TCP.

Component(s)

FlightRPC