What causes "Bad remoteAddress" in walkor/workerman?

Pass a complete address with scheme, host and port, e.g. 'tcp://127.0.0.1:8080', 'ws://site.com:443', or a full path for unix sockets like 'unix:///tmp/app.sock'

walkor/workerman · error · RuntimeException

Bad remoteAddress

Error message

Bad remoteAddress

What it means

Thrown by the AsyncTcpConnection constructor when the $remoteAddress string is too malformed to use. The constructor first tries parse_url(); when that fails it falls back to splitting the string on the first ':' and requires a non-empty remainder (host:port, or a path for unix://). If nothing usable remains after the scheme, Workerman cannot build a connection target and aborts.

Source

Thrown at src/Connection/AsyncTcpConnection.php:188

     */
    protected int $reconnectTimer = 0;

    /**
     * Construct.
     *
     * @param string $remoteAddress
     * @param array $socketContext
     */
    public function __construct(string $remoteAddress, array $socketContext = [])
    {
        $addressInfo = parse_url($remoteAddress);
        if (!$addressInfo) {
            [$scheme, $this->remoteAddress] = explode(':', $remoteAddress, 2);
            if ('unix' === strtolower($scheme)) {
                $this->remoteAddress = substr($remoteAddress, strpos($remoteAddress, '/') + 2);
            }
            if (!$this->remoteAddress) {
                throw new RuntimeException('Bad remoteAddress');
            }
        } else {
            $addressInfo['port'] ??= 0;
            $addressInfo['path'] ??= '/';
            if (!isset($addressInfo['query'])) {
                $addressInfo['query'] = '';
            } else {
                $addressInfo['query'] = '?' . $addressInfo['query'];
            }
            $this->remoteHost = $addressInfo['host'];
            $this->remotePort = $addressInfo['port'];
            $this->remoteURI = "{$addressInfo['path']}{$addressInfo['query']}";
            $scheme = $addressInfo['scheme'] ?? 'tcp';
            $this->remoteAddress = 'unix' === strtolower($scheme)
                ? substr($remoteAddress, strpos($remoteAddress, '/') + 2)
                : $this->remoteHost . ':' . $this->remotePort;
        }

View on GitHub (pinned to 1391112a61)

Solutions

Pass a complete address with scheme, host and port, e.g. 'tcp://127.0.0.1:8080', 'ws://site.com:443', or a full path for unix sockets like 'unix:///tmp/app.sock'
Check that the host/port variables used to build the address are non-empty before constructing the connection
Validate the address with parse_url() in your own config-loading code so bad values fail loudly at startup, not at connect time

Example fix

// before
$host = $config['host'] ?? ''; // empty due to missing config key
$conn = new AsyncTcpConnection("tcp://$host:8080"); // throws 'Bad remoteAddress'

// after
$host = $config['host'] ?? '';
if ($host === '') {
    throw new InvalidArgumentException('config[host] is empty');
}
$conn = new AsyncTcpConnection("tcp://{$host}:8080");

Defensive patterns

Strategy: validation

Validate before calling

$address = "tcp://{$host}:{$port}";
$info = parse_url($address);
$ok = $info !== false
    && (isset($info['host']) && $info['host'] !== '' || strtolower($info['scheme'] ?? '') === 'unix')
    && ($info['scheme'] ?? '') !== '';
if (!$ok || $host === '') {
    throw new InvalidArgumentException("Invalid remote address: $address");
}
$conn = new AsyncTcpConnection($address);

Prevention

Never build connection addresses by naive string concatenation with config values; assert each piece is non-empty first
Load and validate listen/connect addresses once at startup and fail fast with a clear config error
For unix sockets always pass the full absolute path: unix:///var/run/app.sock

When it happens

Trigger: Calling new AsyncTcpConnection() with an address that has no host part: 'tcp:', 'text://', 'unix://', 'ssl://', or an empty string. Also any address where parse_url() returns false and the part after the first ':' is empty or only slashes.

Common situations: The address is assembled from config or environment variables and the host variable is empty at runtime; passing a placeholder like 'ws://' with the host meant to be filled in later; a typo such as 'tcp//host:80'; address truncated by string concatenation bugs.

Related errors

AI-assisted analysis of walkor/workerman@1391112a61 (2026-08-21). Data as JSON: /api/errors/59e41778ea664b66. Report an issue: GitHub.