setsockopt(socket:level:optionName:optionValue:optionLen:): Invalid argument) error when setting up channel

[adam-fowler]

I have an issue in the Hummingbird repo hummingbird-project/hummingbird#812 where a server running on macOS intermittently hangs reporting this error.

Expected behavior

Not to see this error

Steps to reproduce

Reporter in Hummingbird Issue has not found a way to reproduce consistently

[Lukasa]

setsockopt errors can occur if an accepted FD is invalidated in a race, sometimes by connection closure. The error would be expected to be benign in this case, but it's hard to detect the race given the weird error.

[andreasley]

Environment:
macOS 26.4.1 (25E253)
Hummingbird 2.22.0
swift-nio 2.99.0

Issue:

A web server that is accessible from the public internet (no reverse proxy) is stalling/hanging every few hours.
The only way to fix it is to restart the server service.

There is only one helpful message logged: setsockopt(socket:level:optionName:optionValue:optionLen:): Invalid argument) (errno: 22).
From the log entries that follow it, it's clear that the channel was closed.

What I believe happens in SwiftNIO:

1. A TCP connection is established
2. Something unexpected happens on the TCP layer.
3. The file descriptor is invalidated/broken by this.
4. NIO tries to accept the connection, creating a Socket and calling try ignoreSIGPIPE() on the file descriptor.
5. Darwin returns EINVAL to the call to fcntl
6. NIO catches that and throws a NIOFcntlFailedError()
7. The BaseSocketChannel catches this error but doesn't handle it in anyway; the error bubbles up and the channel is closed

This seems the be a Darwin thing (and I've failed to reproduce this on Linux).

Steps to reproduce:

Note: This is showing a different error than the one I'm seeing in production, but is caused by the same underlying issue AFAIK.

1. Run the executable target NIOWebSocketServer from the swift-nio package on host 127.0.0.1 and port 8080
2. Run the python script provided in private conversation
3. The following error is logged: Fatal error: Error raised at top level: NIOPosix.NIOFcntlFailedError()
4. NIOWebSocketServer exits

Possible fix:

I have implemented a possible fix (see main...andreasley:swift-nio:fix-fcntlfailed-close), but that directly contradicts what the test testInstantTCPConnectionResetThrowsError() expects to happen.
This makes me wonder if there's something more generally wrong with how errors are surfaced from the NIOAsyncChannelInboundStream.

Open questions:

• Are there situations in which NIOFcntlFailedError should be handled differently? Is there even still a point to the special handling of EINVAL on Darwin?
• Are there other similar errors that can lead to a broken NIOAsyncChannelInboundStream?
• Why does this only happen when using AsyncChannel?

[Lukasa]

I think this is specifically an issue with how we handle errors in the ServerBootstrap-based channel, actually. Generally speaking this fires errors that are triggered whenever we try to accept a channel down the pipeline. These are usually non-fatal, but NIOAsyncChannel doesn't know that, and indeed cannot know that. Worse, it doesn't have anywhere to put non-fatal errors, because throwing terminates the iteration.

In this instance, I suspect that the right answer is to insert, by default, a channel handler into bound server bootstraps that are using NIOAsyncChannel which suppresses these errors on Darwin. It's probably enough to catch this specific error.

[adam-fowler]

@Lukasa something like this?

final class ServerErrorHandler: ChannelInboundHandler {
    typealias InboundIn = NIOAny
    typealias InboundOut = NIOAny

    let logger: Logger

    init(logger: Logger) {
        self.logger = logger
    }

    func errorCaught(context: ChannelHandlerContext, error: any Error) {
        switch error {
        case is NIOFcntlFailedError:
            logger.debug("Server error: \(error)")
            // don't propagate error
        default:
            logger.error("Server error: \(error)")
            context.fireErrorCaught(error)
        }
    }
}

[Lukasa]

Yep, that would be totally fine.