yiisoft/yii2 · error · yii\base\Exception

Unable to change group ownership of "{$path}" to "{$group}".

Error message

Unable to change group ownership of "{$path}" to "{$group}".

What it means

When chgrp($path, $group) returns false, changeOwnership() throws yii\base\Exception with path and group in the message. Changing a group to anything other than one of the process's own groups requires root; chgrp also fails for a nonexistent group or on read-only filesystems. Like error 269 this is a privilege/lookup failure at the filesystem boundary.

Source

Thrown at framework/helpers/BaseFileHelper.php:1027

        }
        if ($user !== null && $user !== '') {
            if (is_numeric($user)) {
                $user = (int) $user;
            } elseif (!is_string($user)) {
                throw new InvalidArgumentException('The user part of $ownership must be an integer, string, or null.');
            }
            if (!chown($path, $user)) {
                throw new Exception('Unable to change user ownership of "' . $path . '" to "' . $user . '".');
            }
        }
        if ($group !== null && $group !== '') {
            if (is_numeric($group)) {
                $group = (int) $group;
            } elseif (!is_string($group)) {
                throw new InvalidArgumentException('The group part of $ownership must be an integer, string or null.');
            }
            if (!chgrp($path, $group)) {
                throw new Exception('Unable to change group ownership of "' . $path . '" to "' . $group . '".');
            }
        }
    }
}

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Run the step as root (deploy/entrypoint), or add the target group to the running user first.
2. Verify the group before calling: posix_getgrnam($group) !== false.
3. Standardize gids across host/container environments.
4. Catch the Exception and log path + group for diagnosis.

Example fix

// before
\yii\helpers\FileHelper::changeOwnership($upload, ['user' => 'app', 'group' => 'dockerhost']);

// after
$grp = \posix_getgrnam('app');
if ($grp === false) {
    throw new \RuntimeException("Group 'app' not found");
}
\yii\helpers\FileHelper::changeOwnership($upload, ['user' => 'app', 'group' => $grp['gid']]);

if (\function_exists('posix_getgrnam') && \posix_getgrnam($group) === false) {
    throw new \RuntimeException("Unknown group: {$group}");
}
\yii\helpers\FileHelper::changeOwnership($path, ['user' => $user, 'group' => $group]);

try {
    \yii\helpers\FileHelper::changeOwnership($path, ['group' => $group]);
} catch (\yii\base\Exception $e) {
    \Yii::error("chgrp failed (privileges or unknown group): {$e->getMessage()}", 'files');
    throw $e;
}

When it happens

Trigger: An unprivileged process setting a group it does not belong to; a group name/gid that exists on the host but not in the container (or vice versa); group lookup failing through NSS/LDAP; read-only or non-POSIX mounts.

Common situations: Deployment scripts chgrp-ing to service groups while running as CI users; Docker containers with different /etc/group contents than the host; shared-hosting sandboxes that forbid group changes.

Related errors

• Unable to change user ownership of "{$path}" to "{$user}".
• Unable to change mode of "{$path}" to "0{$mode}".
• MemCache requires PHP $extension extension to be loaded.
• Unable to change ownership, "{$path}" is not a file or direc
• $ownership must be an integer, string, array, or null.

AI-assisted analysis of yiisoft/yii2@66f00d18a2 (2026-08-17). Data as JSON: /api/errors/d292950539a49ced. Report an issue: GitHub.