octobercms/october · error · ApplicationException

system::lang.zip.extract_failed

system::lang.zip.extract_failed

Error message

Unable to extract core file ':file'.

What it means

ManagesThemes::extractTheme() unzips a previously downloaded theme archive into themes/<lowercased-dashed-name> using Zip::extract. The archive lives at getFilePath($name . md5($name)), i.e. temp_path(md5($name . md5($name)) . '.arc'). When Zip::extract returns false, the localized message system::lang.zip.extract_failed ('Unable to extract core file ":file".') is thrown with that archive path interpolated.

Source

Thrown at modules/system/classes/updatemanager/ManagesThemes.php:127

        $this->requestServerFile('package/download', $fileCode, [
            'type' => 'theme',
            'name' => $name,
            'version' => SystemHelper::VERSION
        ]);
    }

    /**
     * extractTheme extracts a theme after it has been downloaded.
     */
    public function extractTheme($name)
    {
        $fileCode = $name . md5($name);
        $filePath = $this->getFilePath($fileCode);
        $innerPath = str_replace('.', '-', strtolower($name));

        if (!Zip::extract($filePath, themes_path($innerPath))) {
            throw new ApplicationException(Lang::get('system::lang.zip.extract_failed', ['file' => $filePath]));
        }

        @unlink($filePath);
    }

    /**
     * seedTheme seeds a theme blueprints, data and language files
     */
    public function seedTheme(string $name)
    {
        $themeName = str_replace('.', '-', strtolower($name));
        $theme = CmsTheme::load($themeName);

        if (!$theme->isValid()) {
            throw new ApplicationException("Theme [$name] not found");
        }
        $model = new ThemeSeed;

View on GitHub (pinned to b608633a7e)

Solutions

1. Delete the archive path named in the message (temp_path(md5($name . md5($name)) . '.arc')), re-run downloadTheme($name), then extractTheme($name)
2. Verify the themes/ directory is writable by the web/CLI user (chown/chmod, container user mapping)
3. Confirm the zip extension is loaded: php -m | grep zip, and install/enable ext-zip if missing
4. Check free disk space and remove any half-extracted target directory under themes/ before retrying

Example fix

// before
$manager = UpdateManager::instance();
$manager->extractTheme($name);

// after
$manager = UpdateManager::instance();
$filePath = temp_path(md5($name . md5($name)) . '.arc');
if (!is_readable($filePath) || filesize($filePath) === 0) {
    @unlink($filePath);
    $manager->downloadTheme($name);
}
$manager->extractTheme($name);

$manager = \UpdateManager::instance();
$filePath = temp_path(md5($name . md5($name)) . '.arc');
if (!is_readable($filePath) || filesize($filePath) === 0) {
    @unlink($filePath);
    $manager->downloadTheme($name);
}
$manager->extractTheme($name);

try { $manager->extractTheme($name); } catch (\ApplicationException $ex) { @unlink(temp_path(md5($name . md5($name)) . '.arc')); $manager->downloadTheme($name); $manager->extractTheme($name); }

When it happens

Trigger: Calling extractTheme($name) when the cached .arc archive is corrupt, truncated by an interrupted downloadTheme, or zero bytes; the ZipArchive PHP extension missing or disabled; themes_path() not writable by the PHP process; disk full; a conflicting half-extracted directory already at the target.

Common situations: A previous download was interrupted leaving a partial archive in the temp directory; wrong ownership/permissions on themes/ inside Docker or after a user change; a minimal PHP container without ext-zip.

Related errors

• cms::lang.cms_object.error_creating_directory
• cms::lang.cms_object.error_saving
• cms::lang.lang.error_deleting_file
• Unable to create directory {tempPath}
• Unable to create directory {metaPath}

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