octobercms/october · error · ApplicationException

editor::lang.filesystem.error_renaming

Error message

editor::lang.filesystem.error_renaming

What it means

Thrown by editorRenameFileOrDirectory when the native PHP rename() call (error-suppressed with @) returns false (line 108-109). All validation passed, so this is an OS-level failure: the PHP/webserver user lacks write permission on the file or its directory, the file is locked (Windows), the target is on a different filesystem/mount, or SELinux denies the operation.

Source

Thrown at modules/editor/traits/FileSystemFunctions.php:109

        if (
            !is_dir($originalFullPath) &&
            Config::get('media.clean_vectors', true) &&
            strtolower(File::extension($newName)) === 'svg' &&
            strtolower(File::extension($originalPath)) !== 'svg'
        ) {
            throw new ApplicationException(Lang::get(
                'editor::lang.filesystem.type_not_allowed',
                ['allowed_types' => implode(', ', array_diff($allowedFileExtensions, ['svg']))]
            ));
        }

        $newFullPath = $basePath.'/'.dirname($originalPath).'/'.$newName;
        if (file_exists($newFullPath) && $newFullPath !== $originalFullPath) {
            throw new ApplicationException(Lang::get('editor::lang.filesystem.already_exists'));
        }

        if (!@rename($originalFullPath, $newFullPath)) {
            throw new ApplicationException(Lang::get('editor::lang.filesystem.error_renaming'));
        }
    }

    /**
     * editorDeleteFileOrDirectory
     */
    protected function editorDeleteFileOrDirectory($basePath, $fileList)
    {
        // Delete leaves first
        usort($fileList, function($a, $b) {
            return strlen($b) - strlen($a);
        });

        foreach ($fileList as $path) {
            if (!$this->validateFileSystemPath($path)) {
                throw new ApplicationException(Lang::get('editor::lang.filesystem.invalid_path'));
            }

View on GitHub (pinned to b608633a7e)

Solutions

  1. Give the PHP user write access to the directory and the file: chown -R www-data:www-data themes/<theme>/assets && chmod -R u+rwX (renaming requires write on the DIRECTORY entry)
  2. Check for open handles (lsof <file>) on Windows/locked-file cases and close the program holding it
  3. Verify the mount is read-write (mount | grep themes) and SELinux context is httpd_sys_rw_content_t
  4. If the target crosses filesystems, confirm both source and destination mounts allow the operation for the PHP user

Example fix

# before: root-owned assets block rename
$ ls -la themes/demo/assets | head
# after
$ sudo chown -R www-data:www-data themes/demo/assets
$ sudo chmod -R u+rwX themes/demo/assets
Defensive patterns

Strategy: try-catch

Validate before calling

$orig = $assetsBase.'/'.$originalPath;
$target = $assetsBase.'/'.dirname($originalPath).'/'.$newName;
if (!is_writable($orig) || !is_writable(dirname($target))) {
    // fix ownership/permissions before attempting the rename
}

Try / catch

use October\Rain\Exception\ApplicationException;

try {
    rename($originalFullPath, $newFullPath);
} catch (Throwable $e) {
    // fall back to copy + unlink when rename fails across devices/locks
    if (!@copy($originalFullPath, $newFullPath) || !@unlink($originalFullPath)) {
        throw new ApplicationException(Lang::get('editor::lang.filesystem.error_renaming'));
    }
}

Prevention

When it happens

Trigger: command_onAssetRename that survives every validation but @rename() fails: themes/<theme>/assets not writable by the webserver user; asset files created by root/CLI so the webserver user cannot modify the directory entry; open file handles on Windows; assets mounted read-only (NFS mount, container volume ro).

Common situations: Deployments that write assets as root while PHP runs as www-data; local dev where files were created by a different user than the one running php-fpm; SELinux/AppArmor policies on RHEL-based hosts; synced/mounted theme directories flagged read-only.

Related errors

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/50c56c3faf0d3037. Report an issue: GitHub.