{"id":"7afbc02cc0bb0765","repo":"guzzle/guzzle","slug":"http-3-is-not-supported-by-this-curl-installation","errorCode":null,"errorMessage":"HTTP/3 is not supported by this cURL installation.","messagePattern":"HTTP/3 is not supported by this cURL installation\\.","errorType":"exception","errorClass":"GuzzleHttp\\Exception\\RequestException","httpStatus":null,"severity":"error","filePath":"src/Handler/CurlFactory.php","lineNumber":2130,"sourceCode":"            \\CURLOPT_CUSTOMREQUEST => $easy->request->getMethod(),\n            \\CURLOPT_URL => (string) $uri->withFragment(''),\n            \\CURLOPT_RETURNTRANSFER => false,\n            \\CURLOPT_HEADER => false,\n            \\CURLOPT_CONNECTTIMEOUT_MS => self::DEFAULT_CONNECT_TIMEOUT_MS,\n        ];\n\n        if (CurlVersion::supportsProtocolsStr()) {\n            $conf[(int) \\constant('CURLOPT_PROTOCOLS_STR')] = \\implode(',', $protocols);\n        } else {\n            $conf[\\CURLOPT_PROTOCOLS] = self::curlProtocolMask($protocols);\n        }\n\n        $version = $easy->request->getProtocolVersion();\n        $multiplex = self::normalizeMultiplex($easy->options);\n\n        if ('3' === $version || '3.0' === $version) {\n            if (!\\defined('CURL_HTTP_VERSION_3')) {\n                throw new RequestException('HTTP/3 is not supported by this cURL installation.', $easy->request);\n            }\n\n            $proxy = ProxyEnv::resolveProxySelection($easy->request->getUri(), $easy->options['proxy'] ?? null);\n\n            if (\\in_array($multiplex, [Multiplexing::REQUIRE_EAGER, Multiplexing::REQUIRE_WAIT], true)) {\n                self::assertSelectedProxySupported($proxy->getProxy(), $easy->request);\n\n                if ($proxy->hasProxy()) {\n                    throw new RequestException('Required multiplexing cannot be guaranteed for HTTP/3 requests sent through a proxy.', $easy->request);\n                }\n                if (!CurlVersion::supportsRequiredHttp3Multiplex()) {\n                    throw new RequestException('Required multiplexing for HTTP/3 needs libcurl 8.13.0 or newer built with HTTP/3 support.', $easy->request);\n                }\n                // HTTP/3 or fail: required multiplexing never downgrades, not\n                // even to HTTP/2.\n                $conf[\\CURLOPT_HTTP_VERSION] = (int) \\constant('CURL_HTTP_VERSION_3ONLY');\n            } else {\n                $conf[\\CURLOPT_HTTP_VERSION] = $proxy->hasProxy()","sourceCodeStart":2112,"sourceCodeEnd":2148,"githubUrl":"https://github.com/guzzle/guzzle/blob/9b200fc5805036b331d6031199880dadecae0275/src/Handler/CurlFactory.php#L2112-L2148","documentation":"Thrown by getDefaultConf() when the request protocol version is HTTP/3 ('3' or '3.0') but the PHP cURL extension does not define CURL_HTTP_VERSION_3, meaning libcurl was not built with HTTP/3 support. HTTP/3 requires a specially built libcurl with a QUIC/HTTP3 backend (ngtcp2, quiche, etc.).","triggerScenarios":"Calling $client->get($url, ['version' => '3']) (or 3.0) on a standard libcurl build without HTTP/3 support.","commonSituations":"Most default libcurl installations lack HTTP/3; requesting version 3 because the server supports it without checking the client; testing HTTP/3 in CI with a stock image.","solutions":["Use HTTP/2 ('2' or '2.0') instead, which is widely supported and negotiates with HTTP/3-capable servers via Alt-Svc.","Install a libcurl build with HTTP/3 support (e.g. compiled with ngtcp2/quiche) and rebuild the PHP cURL extension.","Remove the 'version' => '3' option and let Guzzle/libcurl negotiate."],"exampleFix":"// before\n$client->get($url, ['version' => '3']);\n// after\n$client->get($url, ['version' => '2']);","handlingStrategy":"validation","validationCode":"if (($options['version'] ?? null) === '3' && !defined('CURL_HTTP_VERSION_3')) {\n    throw new \\RuntimeException('HTTP/3 not supported by this cURL build; use version 2 or upgrade libcurl.');\n}","typeGuard":"function libcurlSupportsHttp3(): bool { return defined('CURL_HTTP_VERSION_3'); }","tryCatchPattern":"try {\n    $client->get($url, ['version' => '3']);\n} catch (\\GuzzleHttp\\Exception\\RequestException $e) {\n    // Fall back to HTTP/2 or upgrade libcurl.\n}","preventionTips":["Detect CURL_HTTP_VERSION_3 at boot before setting version 3.","Default to HTTP/2 for broad compatibility with HTTP/3 servers via Alt-Svc."],"tags":["curl","http3","environment","libcurl-version","request-options"],"analyzedSha":"9b200fc5805036b331d6031199880dadecae0275","analyzedAt":"2026-08-04T21:24:26.648Z","schemaVersion":2}