{"record":{"id":"4d1e260b65d47293","repo":"yiisoft/yii2","slug":"unable-to-change-user-ownership-of-path-to","errorCode":null,"errorMessage":"Unable to change user ownership of \"{$path}\" to \"{$user}\".","messagePattern":"Unable to change user ownership of \"(.+?)\" to \"(.+?)\"\\.","errorType":"exception","errorClass":"yii\\base\\Exception","httpStatus":null,"severity":"error","filePath":"framework/helpers/BaseFileHelper.php","lineNumber":1017,"sourceCode":"            }\n        }\n\n        if ($mode !== null) {\n            if (!is_int($mode)) {\n                throw new InvalidArgumentException('$mode must be an integer or null.');\n            }\n            if (!chmod($path, $mode)) {\n                throw new Exception('Unable to change mode of \"' . $path . '\" to \"0' . decoct($mode) . '\".');\n            }\n        }\n        if ($user !== null && $user !== '') {\n            if (is_numeric($user)) {\n                $user = (int) $user;\n            } elseif (!is_string($user)) {\n                throw new InvalidArgumentException('The user part of $ownership must be an integer, string, or null.');\n            }\n            if (!chown($path, $user)) {\n                throw new Exception('Unable to change user ownership of \"' . $path . '\" to \"' . $user . '\".');\n            }\n        }\n        if ($group !== null && $group !== '') {\n            if (is_numeric($group)) {\n                $group = (int) $group;\n            } elseif (!is_string($group)) {\n                throw new InvalidArgumentException('The group part of $ownership must be an integer, string or null.');\n            }\n            if (!chgrp($path, $group)) {\n                throw new Exception('Unable to change group ownership of \"' . $path . '\" to \"' . $group . '\".');\n            }\n        }\n    }\n}\n","sourceCodeStart":999,"sourceCodeEnd":1032,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/helpers/BaseFileHelper.php#L999-L1032","documentation":"When the resolved user passes type checks but chown($path, $user) returns false, changeOwnership() throws yii\\base\\Exception naming the path and user. On Unix, changing a file's owner requires root (CAP_CHOWN); chown also fails when the user does not exist in the passwd database. This is a privilege/lookup failure, not an argument problem.","triggerScenarios":"A non-root process chown-ing a file to another user; a uid or name absent from /etc/passwd (typical host-vs-container uid mismatches); a container dropping CAP_CHOWN; a read-only filesystem; a typo'd username string.","commonSituations":"Web requests trying to re-own uploaded files to a service user; containerized apps using host usernames that exist only outside the container; deploy scripts assuming root but running as an unprivileged CI user; LDAP/NSS hiccups where user lookups intermittently fail.","solutions":["Run the ownership step as root in the deploy/entrypoint script rather than in application code.","Verify the user exists first: posix_getpwnam($user) !== false (or check /etc/passwd) before calling.","Use consistent numeric uid/gid mappings between host and containers instead of names.","Catch the Exception and log path + user so failures surface in monitoring."],"exampleFix":"// before\n\\yii\\helpers\\FileHelper::changeOwnership($upload, 'appuser');\n\n// after\n$user = \\posix_getpwnam('appuser');\nif ($user === false) {\n    throw new \\RuntimeException(\"User 'appuser' not found on this system\");\n}\n\\yii\\helpers\\FileHelper::changeOwnership($upload, $user['uid']);","handlingStrategy":"validation","validationCode":"// Only root can chown arbitrarily; verify the target user exists\nif (\\function_exists('posix_getuid') && \\posix_getuid() !== 0) {\n    // allowed only if process already owns the file — check first\n    $stat = stat($path);\n    if ($stat === false || $stat['uid'] !== \\posix_getuid()) {\n        throw new \\RuntimeException('chown requires root or file ownership');\n    }\n}\nif (\\posix_getpwnam($user) === false) {\n    throw new \\RuntimeException(\"Unknown user: {$user}\");\n}\n\\yii\\helpers\\FileHelper::changeOwnership($path, $user);","typeGuard":null,"tryCatchPattern":"try {\n    \\yii\\helpers\\FileHelper::changeOwnership($path, $user);\n} catch (\\yii\\base\\Exception $e) {\n    \\Yii::error(\"chown failed (privileges or unknown user): {$e->getMessage()}\", 'files');\n    throw $e;\n}","preventionTips":["Run ownership changes as root in the deploy/entrypoint phase, not in web requests.","Verify usernames against posix_getpwnam() before calling.","Standardize uid values across host and containers instead of relying on name resolution.","Treat chown failures as deployment errors, not application warnings."],"tags":["ownership","chown","privileges","environment","yii2"],"backgroundTag":"chown-permission-denied","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}