{"record":{"id":"65f0be163dfd5eaf","repo":"thephpleague/flysystem","slug":"could-not-set-utf-8-mode-for-connection-host","errorCode":null,"errorMessage":"Could not set UTF-8 mode for connection: {host}::{port}","messagePattern":"Could not set UTF-8 mode for connection: (.+?)::(.+?)","errorType":"exception","errorClass":"UnableToEnableUtf8Mode","httpStatus":null,"severity":"error","filePath":"src/Ftp/FtpConnectionProvider.php","lineNumber":77,"sourceCode":"    {\n        if ( ! @ftp_login($connection, $options->username(), $options->password())) {\n            throw new UnableToAuthenticate();\n        }\n    }\n\n    /**\n     * @param resource $connection\n     */\n    private function enableUtf8Mode(FtpConnectionOptions $options, $connection): void\n    {\n        if ( ! $options->utf8()) {\n            return;\n        }\n\n        $response = @ftp_raw($connection, \"OPTS UTF8 ON\");\n\n        if ( ! in_array(substr($response[0], 0, 3), ['200', '202'])) {\n            throw new UnableToEnableUtf8Mode(\n                'Could not set UTF-8 mode for connection: ' . $options->host() . '::' . $options->port()\n            );\n        }\n    }\n\n    /**\n     * @param resource $connection\n     */\n    private function ignorePassiveAddress(FtpConnectionOptions $options, $connection): void\n    {\n        $ignorePassiveAddress = $options->ignorePassiveAddress();\n\n        if ( ! is_bool($ignorePassiveAddress) || ! defined('FTP_USEPASVADDRESS')) {\n            return;\n        }\n\n        if ( ! @ftp_set_option($connection, FTP_USEPASVADDRESS, ! $ignorePassiveAddress)) {\n            throw UnableToSetFtpOption::whileSettingOption('FTP_USEPASVADDRESS');","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/thephpleague/flysystem/blob/b277b5dc3d56650b68904117124e79c851e12376/src/Ftp/FtpConnectionProvider.php#L59-L95","documentation":"When FtpConnectionOptions has utf8 = true, FtpConnectionProvider::enableUtf8Mode() sends 'OPTS UTF8 ON' via ftp_raw and requires the response code to start with 200 or 202. Any other reply throws UnableToEnableUtf8Mode with 'Could not set UTF-8 mode for connection: host::port'. It fires right after login, during connection setup.","triggerScenarios":"Constructing FtpAdapter (or first adapter operation that opens a connection) with utf8 enabled against a server that does not advertise/support the UTF8 option (many Windows/IIS or embedded FTP servers return 500 'Command not understood').","commonSituations":"Copying FtpConnectionOptions tuned for a Linux server to an IIS/appliance FTP endpoint; enabling utf8 defensively 'for unicode filenames' without checking server support; embedded devices (printers, NAS boxes) with minimal FTP implementations.","solutions":["Set 'utf8' => false in FtpConnectionOptions if the server does not support OPTS UTF8 ON.","Keep utf8 = true only for servers that advertise UTF8 in their FEAT response — verify with an FTP client sending FEAT.","If UTF-8 filenames matter and the server lacks the option, encode filenames yourself before writing paths.","Catch UnableToEnableUtf8Mode during adapter warm-up to fail fast with a configuration-specific message."],"exampleFix":"// before\n$options = FtpConnectionOptions::lazy('ftp.example.com', '/', FTP_NATIVE, null, 'u', 'p', null, false, true); // utf8: true\nnew Filesystem(new FtpAdapter($options)); // server replies 500 -> throws\n\n// after (server without UTF8 support)\n$options = FtpConnectionOptions::lazy('ftp.example.com', '/', FTP_NATIVE, null, 'u', 'p', null, false, false); // utf8: false","handlingStrategy":"validation","validationCode":"// Probe server capability once, then build options accordingly\n$features = ftp_raw($connection, 'FEAT');\n$supportsUtf8 = array_any($features ?? [], fn ($l) => str_contains(strtoupper($l), 'UTF8'));\n\n$options = FtpConnectionOptions::lazy($host, '/', FTP_NATIVE, null, $user, $pass, null, $ssl, $supportsUtf8);","typeGuard":null,"tryCatchPattern":"use League\\Flysystem\\Ftp\\UnableToEnableUtf8Mode;\n\ntry {\n    $filesystem->listContents('/');\n} catch (UnableToEnableUtf8Mode $e) {\n    // server answered something other than 200/202 to OPTS UTF8 ON:\n    // rebuild adapter with utf8 disabled rather than retrying\n    $options = FtpConnectionOptions::lazy($host, '/', FTP_NATIVE, null, $user, $pass, null, $ssl, false);\n    $filesystem = new Filesystem(new FtpAdapter($options));\n}","preventionTips":["Enable utf8 only for servers that advertise it via FEAT.","Keep FTP connection options per-host in config, not one shared preset.","If UTF-8 filenames are required on a non-supporting server, transliterate/encode names application-side."],"tags":["php","flysystem","ftp","utf8","connection-options","server-capability"],"backgroundTag":"ftp-utf8-mode-failed","analyzedSha":"b277b5dc3d56650b68904117124e79c851e12376","analyzedAt":"2026-08-17T04:28:35.741Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}