walkor/workerman · error · RuntimeException

Invalid protocol scheme '$scheme'

Error message

Invalid protocol scheme '$scheme'

What it means

AsyncUdpConnection splits the address on the first ':' and expects the scheme 'udp' for a plain UDP transport. Any other scheme is treated as an application-layer protocol class name, and before building '\Protocols\<Scheme>' Workerman validates it against /^[a-zA-Z][a-zA-Z0-9]*$/. A scheme containing hyphens, dots, leading digits or symbols throws immediately.

Source

Thrown at src/Connection/AsyncUdpConnection.php:85

     * @var array
     */
    protected array $contextOption = [];

    /**
     * Construct.
     *
     * @param string $remoteAddress
     * @throws Throwable
     */
    public function __construct($remoteAddress, $contextOption = [])
    {
        // Get the application layer communication protocol and listening address.
        [$scheme, $address] = explode(':', $remoteAddress, 2);
        // Check application layer protocol class.
        if ($scheme !== 'udp') {
            // Validate scheme contains only safe characters for class name resolution.
            if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $scheme)) {
                throw new RuntimeException("Invalid protocol scheme '$scheme'");
            }
            $scheme = ucfirst($scheme);
            $this->protocol = '\\Protocols\\' . $scheme;
            if (!class_exists($this->protocol)) {
                $this->protocol = "\\Workerman\\Protocols\\$scheme";
                if (!class_exists($this->protocol)) {
                    throw new RuntimeException("class \\Protocols\\$scheme not exist");
                }
            }
        }

        $this->remoteAddress = substr($address, 2);
        $this->contextOption = $contextOption;
    }

    /**
     * For udp package.
     *

View on GitHub (pinned to 1391112a61)

Solutions

  1. Use the exact scheme 'udp://' for plain UDP, e.g. new AsyncUdpConnection('udp://1.2.3.4:53')
  2. For a custom protocol, rename the scheme to /^[a-zA-Z][a-zA-Z0-9]*$/ (e.g. 'mydns://host:53') and provide Protocols\Mydns
  3. Trim and validate the scheme portion of the address string before constructing the connection

Example fix

// before
$conn = new AsyncUdpConnection('my-dns://8.8.8.8:53'); // throws Invalid protocol scheme 'my-dns'

// after
$conn = new AsyncUdpConnection('mydns://8.8.8.8:53'); // uses Protocols\Mydns
Defensive patterns

Strategy: validation

Validate before calling

$scheme = strtolower(explode(':', (string)$address, 2)[0]);
if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $scheme)) {
    throw new InvalidArgumentException("Bad UDP protocol scheme: '$scheme'");
}
$conn = new AsyncUdpConnection($address);

Prevention

When it happens

Trigger: new AsyncUdpConnection('my-proto://1.2.3.4:53') (hyphen), scheme starting with a digit like '2dns://host', an address with junk before ':' such as '//udp://host:53', or an empty address string.

Common situations: Custom UDP-based protocol named with dashes instead of alphanumeric PascalCase; address assembled from config where the scheme variable contains whitespace or a typo; copy-pasting a TCP address scheme into a UDP connection.

Related errors

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