Skip to main content

Troubleshooting

SymptomCauseFix
io_uring warnings for file operations in stderrkernel < 5.1; OpenSwoole retries its io_uring file engineset server.log_file or server.log_level => 'error' (file I/O still works via the thread pool)
Unable to create event-loop reactorreactor => 'io_uring' on an old kernelOmnitrix refuses this at config time; use epoll
Requests hang after some traffic, workers idleworker blocked writing to a full stderr pipelog to a file / a drained collector
Socket#N has already been bound to another coroutineone connection used by two coroutinesnever share clients; use the pools (OwnershipViolationException catches this early)
API must be called in the coroutine at shutdowncoroutine APIs used in WorkerStopOmnitrix pools handle this; custom resources must not use channels/sockets in stop hooks
Co::sleep(0.5) returns immediatelyOpenSwoole 26.2 truncates to intuse Async::sleep(0.5)
must be forked outside the coroutineProcess::start() inside a requestuse the CPU pool ($app->cpu())
A standalone script never exits after Coroutine::run()a pool timer is still armedclose clients you created before returning
1 s latency spikes on bursts of new connectionslisten backlog (somaxconn) too smallraise kernel limits; use keep-alive
PoolExhaustedException / TimeoutException from poolsmore concurrent work than pool.maxraise the pool, bound fan-out (Async::all(..., concurrency:)), or shed load
TlsException calling an internal serviceprivate CA->withCaFile('/etc/ssl/internal-ca.pem') or http_client.ca_file
DnsException for public hosts in containersresolver not reachablecheck /etc/resolv.conf; OpenSwoole uses c-ares with that config