[MacOS] Cowboy Listener Unreachable After Max Open Ports Reached

[Kozaky]

Hi,

I ran a small load test with K6 against a dummy WebSocket application using Cowboy. During the test, the system reached the maximum number of open ports. After hitting this limit, the Cowboy listener appears to enter an inconsistent state. For example:

❯ lsof -i :3000
COMMAND   PID    USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
beam.smp 6236 juliogc   39u  IPv4 0xb0cec2ba38c3c8df      0t0  TCP *:hbci (CLOSED)

Here, the port shows as CLOSED and the server no longer accepts connections, even after the load test has stopped. Restarting the application or the Cowboy listener resolves the issue, but it seems like the server should be able to recover automatically.

Steps to Reproduce:

• Run a WebSocket server with Cowboy on macOS.
• Launch a high-load test (e.g., K6) to reach the system’s maximum number of open ports.
• Observe the listener state via lsof -i :.
• Attempt to connect — connections are refused.

Expected Behavior:
The Cowboy listener should either:

• Recover automatically after the system clears some sockets, or
• Fail gracefully with a clear error without making the port permanently unreachable.

Actual Behavior:
The listener stops accepting new connections silently and requires a manual restart.

Environment:

• macOS: Sonoma 14.6.1
• Erlang/OTP: 28
• Cowboy: 2.14.2

Notes:
This may be related to TIME_WAIT socket exhaustion or OS-level ephemeral port limits. A mechanism to gracefully handle port exhaustion would improve robustness under load.

[essen]

I'll try tomorrow. Logs would be helpful as Ranch likely error'd out somewhere.

That said, you're supposed to configure FD limits to be higher than the worst case scenario you're expecting if it's a server application you're building.

[Kozaky]

Right now I'm just running it local and I was a bit surprised with this behaviour, specially because I don't see any error on ranch/cowboy side.

I was able to link it to these errors, but even with debug errors I do not get more info:

2025-12-14T20:38:25.795180+01:00 ws_handler:terminate/3:80 error: Unexpected termination: {error,enotconn}
2025-12-14T20:38:25.816219+01:00 gen_server:error_info/7:2785 error: Generic server <0.541.0> terminating. Reason: {connection_lost,closed}. Last message: {gun_down,<0.542.0>,ws,closed,[#Ref<0.2184898192.3680239623.247084>]}. State: {state,<0.542.0>,#Ref<0.2184898192.3680239623.247084>,#Ref<0.2184898192.3680501763.247311>}.

The last error is from my own listener to another websocket server, it seems to crash at the same time, but that one is able to self-recover once the supervisor restart it.

[essen]

If there's a problem at the listener then ranch_conns_sup, ranch_server, ranch_acceptor, ranch_acceptors_sup and other Ranch modules are good to trace. Normally you're supposed to reach https://github.com/ninenines/ranch/blob/master/src/ranch_acceptor.erl#L49 but maybe macOS is being funny again.

[Kozaky]

load-test.js

I quickly took a look and I didn’t find anything useful, no errors and just logs about the TCP handshake and sending messages.

I am not sure this is connected to the emfile, I had that before and solved it increasing the limits (I am not sure if the cowboy server was also in this inconsistent state back then, maybe I check tomorrow).

For some reason, it seems to fail faster and easier if you run the load test from another laptop, in my case at around 2000 open connections. I attached the k6 file here in case it is useful.

[essen]

emfile is what normally happens when running out of file descriptors. I'll try to see if I can reproduce, but the macOS machine I have around is a corporate infested environment so we'll see.

I tried asking Grok, seems that even if you ulimit -n you can reach other kinds of limits like 2560 fds, depending on hardware and shell setup (for example M2 with zsh), and some users are not able to go beyond that value. That's close enough to what you're seeing. Perhaps a different shell or environment would bypass that issue.

What would likely help in improving Cowboy is adding a log in this clause: https://github.com/ninenines/ranch/blob/master/src/ranch_acceptor.erl#L58 and printing the error reason. My guess would be it gives {error,enotconn} like in your logs, and that should be handled like {error,closed}.