{"id":"08f1af5a1db547ed","repo":"guzzle/guzzle","slug":"the-transport-sharing-option-requires-persistent-08f1af","errorCode":null,"errorMessage":"The \"transport_sharing\" option requires persistent transport sharing, which is only available through cURL share handles.","messagePattern":"The \"transport_sharing\" option requires persistent transport sharing, which is only available through cURL share handles\\.","errorType":"validation","errorClass":"GuzzleHttp\\Exception\\InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Handler/StreamHandler.php","lineNumber":1370,"sourceCode":"                'cafile' => 'the \"verify\" request option',\n                'capath' => 'the \"verify\" request option',\n                'crypto_method' => 'the \"crypto_method\" request option',\n                'local_cert' => 'the \"cert\" request option',\n                'local_pk' => 'the \"ssl_key\" request option',\n                'max_proto_version' => 'the \"crypto_method_max\" request option',\n                'min_proto_version' => 'the \"crypto_method\" request option',\n                'passphrase' => 'the \"cert\" or \"ssl_key\" request option',\n                'peer_name' => 'the request URI',\n                'verify_peer' => 'the \"verify\" request option',\n                'verify_peer_name' => 'the \"verify\" request option',\n            ],\n        ];\n    }\n\n    private function assertTransportSharingSupported(): void\n    {\n        if ($this->transportSharingMode === TransportSharing::PERSISTENT_REQUIRE) {\n            throw new InvalidArgumentException('The \"transport_sharing\" option requires persistent transport sharing, which is only available through cURL share handles.');\n        }\n\n        if ($this->transportSharingMode === TransportSharing::HANDLER_REQUIRE) {\n            throw new InvalidArgumentException('The \"transport_sharing\" option requires transport sharing, but the stream handler does not support it.');\n        }\n    }\n\n    /**\n     * @param mixed $value as passed via Request transfer options.\n     *\n     * @return array{0: string, 1: string|null}\n     */\n    private static function normalizeTlsFileOption(\n        string $option,\n        #[\\SensitiveParameter]\n        $value\n    ): array {\n        $passphrase = null;","sourceCodeStart":1352,"sourceCodeEnd":1388,"githubUrl":"https://github.com/guzzle/guzzle/blob/9b200fc5805036b331d6031199880dadecae0275/src/Handler/StreamHandler.php#L1352-L1388","documentation":"Raised in assertTransportSharingSupported() at src/Handler/StreamHandler.php:1370 when the handler was constructed with transport_sharing = TransportSharing::PERSISTENT_REQUIRE. That mode demands cross-process / cross-handle state sharing via cURL share handles, which the stream handler cannot provide, so the request is rejected on first use.","triggerScenarios":"new StreamHandler(['transport_sharing' => TransportSharing::PERSISTENT_REQUIRE]) followed by any request through that handler.","commonSituations":"Sharing a config array across CurlHandler and StreamHandler; defaulting the whole application to PERSISTENT_REQUIRE; assuming all handlers support persistent sharing.","solutions":["Downgrade to TransportSharing::PERSISTENT_PREFER (silently no-ops on StreamHandler) or TransportSharing::NONE.","Use CurlHandler or CurlMultiHandler when you require persistent sharing.","Branch the transport_sharing option by handler type."],"exampleFix":"// before\n$handler = new StreamHandler(['transport_sharing' => TransportSharing::PERSISTENT_REQUIRE]);\n\n// after\n$handler = new StreamHandler(['transport_sharing' => TransportSharing::PERSISTENT_PREFER]);\n// or use new CurlMultiHandler(['transport_sharing' => TransportSharing::PERSISTENT_REQUIRE])","handlingStrategy":"validation","validationCode":"if ($handler instanceof \\GuzzleHttp\\Handler\\StreamHandler\n    && $transportSharing === \\GuzzleHttp\\TransportSharing::PERSISTENT_REQUIRE\n) {\n    throw new InvalidArgumentException(\n        'StreamHandler cannot provide persistent transport sharing; use PERSISTENT_PREFER or a cURL handler.'\n    );\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Reserve PERSISTENT_REQUIRE for cURL-based handlers.","Use PERSISTENT_PREFER when you want sharing opportunistically across handler types.","Branch the transport_sharing setting by handler in shared config builders."],"tags":["transport-sharing","handler","curl","options"],"analyzedSha":"9b200fc5805036b331d6031199880dadecae0275","analyzedAt":"2026-08-04T21:24:26.648Z","schemaVersion":2}