{"record":{"id":"38e1812b62b89daa","repo":"guzzle/guzzle","slug":"the-multiplex-request-option-cannot-be-multiplex","errorCode":null,"errorMessage":"The \"multiplex\" request option cannot be Multiplexing::NONE on a CurlMultiHandler that permits multiplexing and requires persistent transport sharing; set the \"multiplex\" client or CurlMultiHandler constructor option to Multiplexing::NONE, or use TransportSharing::PERSISTENT_PREFER.","messagePattern":"The \"multiplex\" request option cannot be Multiplexing::NONE on a CurlMultiHandler that permits multiplexing and requires persistent transport sharing; set the \"multiplex\" client or CurlMultiHandler constructor option to Multiplexing::NONE, or use TransportSharing::PERSISTENT_PREFER\\.","errorType":"validation","errorClass":"\\InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Handler/CurlMultiHandler.php","lineNumber":432,"sourceCode":"            return;\n        }\n\n        if (!$this->ownsFactory) {\n            throw new InvalidArgumentException('The \"multiplex\" request option can only be Multiplexing::NONE on a CurlMultiHandler with a custom \"handle_factory\" when the handler\\'s own \"multiplex\" option is Multiplexing::NONE, because the guarantee is enforced against the native easy handle the factory controls.');\n        }\n\n        $version = $easy->request->getProtocolVersion();\n        if ('1.0' !== $version && '1.1' !== $version) {\n            throw new InvalidArgumentException('The \"multiplex\" request option can only be Multiplexing::NONE for an HTTP/1.x request on a CurlMultiHandler that permits multiplexing; set the \"multiplex\" client or CurlMultiHandler constructor option to Multiplexing::NONE to disable multiplexing for every transfer, or send the request with its \"version\" option set to \"1.1\".');\n        }\n\n        if (null !== $this->shareHandleState && TransportSharing::PERSISTENT_REQUIRE === $this->shareHandleState->mode) {\n            // The matcher-window hardening below may force a fresh\n            // connection, which required persistent sharing forbids because\n            // it disables connection reuse (CurlFactory applies the same\n            // rule to the raw option); rejected on every runtime so\n            // acceptance stays version-independent.\n            throw new InvalidArgumentException('The \"multiplex\" request option cannot be Multiplexing::NONE on a CurlMultiHandler that permits multiplexing and requires persistent transport sharing; set the \"multiplex\" client or CurlMultiHandler constructor option to Multiplexing::NONE, or use TransportSharing::PERSISTENT_PREFER.');\n        }\n\n        if (\\defined('CURLOPT_HTTPAUTH')\n            && isset($options['curl'])\n            && \\is_array($options['curl'])\n            && \\array_key_exists((int) \\constant('CURLOPT_HTTPAUTH'), $options['curl'])\n        ) {\n            // Key presence alone conflicts: challenge-response retries are\n            // libcurl-internal follows, which disarm CURLOPT_FRESH_CONNECT\n            // (reuse_fresh && !this_is_a_follow), so the hardening below\n            // cannot cover them.\n            throw new InvalidArgumentException('The \"multiplex\" request option cannot be Multiplexing::NONE combined with the raw CURLOPT_HTTPAUTH cURL option on a CurlMultiHandler that permits multiplexing; remove the raw option, or set the \"multiplex\" client or CurlMultiHandler constructor option to Multiplexing::NONE.');\n        }\n\n        if (Psr7\\Utils::caselessContains($easy->request->getHeaderLine('Expect'), '100-continue')) {\n            // libcurl arms its Expect handling by a caseless substring scan\n            // of the header value (Curl_compareheader), so any value\n            // containing 100-continue can make a 417 response retry as an","sourceCodeStart":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/guzzle/guzzle/blob/d1cbca76970939a9c2ced55b1e25ea26f34fc773/src/Handler/CurlMultiHandler.php#L414-L450","documentation":"Required persistent sharing forbids `CURLOPT_FRESH_CONNECT` because it kills connection reuse, but `Multiplexing::NONE` on a multiplexing handler may need to force a fresh connection to harden the sole-use guarantee on certain libcurl versions. To keep the guarantee version-independent, Guzzle rejects the combination outright.","triggerScenarios":"Handler configured with `transport_sharing => TransportSharing::PERSISTENT_REQUIRE`, request with `'multiplex' => Multiplexing::NONE` over HTTP/1.x on a handler that permits multiplexing. Guarded at line 426.","commonSituations":"Requiring cross-handler connection reuse for performance while still marking specific sensitive requests as sole-use.","solutions":["Disable multiplexing globally via the `multiplex` client/handler option (`Multiplexing::NONE`), which makes NONE hold without forcing fresh connections.","Switch required sharing to `TransportSharing::PERSISTENT_PREFER`.","Drop the per-request `Multiplexing::NONE`."],"exampleFix":"// before\nnew CurlMultiHandler(['transport_sharing' => TransportSharing::PERSISTENT_REQUIRE]);\n$client->get($url, ['multiplex' => Multiplexing::NONE]);\n\n// after\nnew CurlMultiHandler([\n    'transport_sharing' => TransportSharing::PERSISTENT_REQUIRE,\n    'multiplex' => Multiplexing::NONE,\n]);","handlingStrategy":"validation","validationCode":"$persistReq = ($hOpts['transport_sharing'] ?? null) === TransportSharing::PERSISTENT_REQUIRE;\n$handlerPermitsMultiplex = ($hOpts['multiplex'] ?? null) !== Multiplexing::NONE;\nif ($persistReq && $handlerPermitsMultiplex\n    && ($reqOpts['multiplex'] ?? null) === Multiplexing::NONE\n) {\n    throw new \\LogicException('PERSISTENT_REQUIRE sharing conflicts with per-request Multiplexing::NONE');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["PERSISTENT_REQUIRE and per-request sole-use are incompatible; pick one strategy.","If sole-use matters, disable multiplexing at the handler level rather than per request."],"tags":["config","multiplexing","transport-sharing"],"backgroundTag":null,"analyzedSha":"d1cbca76970939a9c2ced55b1e25ea26f34fc773","analyzedAt":"2026-08-06T00:37:27.795Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}