composer/composer · error · RuntimeException

Could not retrieve RAR archive entries

Error message

Could not retrieve RAR archive entries

What it means

Thrown by RarDownloader::extract() when RarArchive::getEntries() returns false after a successful open(). The archive opened but its entry list could not be enumerated, so there is nothing to iterate and extract.

Solutions

  1. Test the archive with `unrar l <file>` to confirm the entry list is readable.
  2. If the header is encrypted, supply the password or avoid such dist packages.
  3. Re-download the archive in case of corruption.
  4. Upgrade the rar extension / unrar binary to a newer version.
Defensive patterns

Strategy: validation

Validate before calling

if (class_exists(\RarArchive::class)) {
    $r = \RarArchive::open($file);
    if ($r !== false) {
        if ($r->getEntries() === false) {
            throw new \RuntimeException('RAR entry list unreadable (encrypted header or corrupt).');
        }
        $r->close();
    }
}

Try / catch

try {
    $downloader->install($package, $path);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'Could not retrieve RAR archive entries')) {
        // re-download; if header-encrypted, avoid this dist package
    } else {
        throw $e;
    }
}

Prevention

When it happens

Trigger: RarArchive::open() succeeded (returned an object) but getEntries() returns false — a partially corrupt header, an encrypted archive header, or an extension-level read failure.

Common situations: The RAR has an encrypted file list (header encryption) the extension cannot read without a password; corrupt central directory; extension bug on certain RAR variants.

Related errors

AI-assisted analysis of composer/composer@c435d285c9 (2026-08-07). Data as JSON: /api/errors/0e95315b33e1701a. Report an issue: GitHub.

Appendix: source

Thrown at src/Composer/Downloader/RarDownloader.php:68

                . $iniMessage . "\n" . $processError;

            if (!Platform::isWindows()) {
                $error = "Could not decompress the archive, enable the PHP rar extension.\n" . $iniMessage;
            }

            throw new \RuntimeException($error);
        }

        $rarArchive = RarArchive::open($file);

        if (false === $rarArchive) {
            throw new \UnexpectedValueException('Could not open RAR archive: ' . $file);
        }

        $entries = $rarArchive->getEntries();

        if (false === $entries) {
            throw new \RuntimeException('Could not retrieve RAR archive entries');
        }

        foreach ($entries as $entry) {
            if (false === $entry->extract($path)) {
                throw new \RuntimeException('Could not extract entry');
            }
        }

        $rarArchive->close();

        return \React\Promise\resolve(null);
    }
}

View on GitHub (pinned to c435d285c9)