paragonie/random_compat · critical · Exception

There is no suitable CSPRNG installed on your system

Error message

There is no suitable CSPRNG installed on your system

What it means

This is random_compat's terminal fallback: if the library could not find any cryptographically secure random number generator at load time (no libsodium, no mcrypt, no /dev/urandom, no CAPICOM on Windows, and PHP < 7 without any suitable source), every call to random_bytes() throws this Exception unconditionally.

Solutions

1. Upgrade to PHP 7+ where random_bytes() is native and this polyfill branch never executes.
2. Ensure /dev/urandom exists and is readable by the PHP process (fix open_basedir, chroot, or container device mounts).
3. Install/enable paragonie/sodium_compat or the libsodium extension so a userspace/kernel CSPRNG is available.
4. On Windows with PHP 5.x, enable the com_dotnet extension so CAPICOM can be used as the entropy source.

Example fix

// before (docker run without devices)
$bytes = random_bytes(32);

// after (docker-compose.yml)
// services:
//   app:
//     devices:
//       - /dev/urandom:/dev/urandom
// or upgrade the image to php:7+
$bytes = random_bytes(32);

// capability check at app bootstrap
if (!function_exists('random_bytes') && !is_readable('/dev/urandom') && !extension_loaded('libsodium')) {
    error_log('FATAL: no CSPRNG available on this host');
}

try {
    $bytes = random_bytes(32);
} catch (Exception $e) {
    // no CSPRNG: fail closed for security-sensitive use
    throw new RuntimeException('Secure randomness unavailable; cannot continue safely', 0, $e);
}

When it happens

Trigger: Calling random_bytes() on a system where no CSPRNG was detected: non-Windows hosts without /dev/urandom (some chroots, restricted containers, OpenBSD in certain modes), Windows without CAPICOM under PHP < 7, or open_basedir/open_basedir-like restrictions blocking /dev/urandom reads.

Common situations: Shared hosting with restricted open_basedir, minimal Docker images lacking /dev/urandom mounts, very old PHP 5.x on Windows, or platforms where com_dotnet extension is disabled so CAPICOM is unavailable.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Could not gather sufficient random data
• COM does not exist
• Environment misconfiguration: /dev/urandom cannot be read.
• Could not gather sufficient random data
• Could not gather sufficient random data

AI-assisted analysis of paragonie/random_compat@b5d188cc9d (2026-09-13). Data as JSON: /api/errors/6d7892875559cd98. Report an issue: GitHub.

Appendix: source

Thrown at lib/random.php:214

    }

    /**
     * throw new Exception
     */
    if (!is_callable('random_bytes')) {
        /**
         * We don't have any more options, so let's throw an exception right now
         * and hope the developer won't let it fail silently.
         *
         * @param mixed $length
         * @psalm-suppress InvalidReturnType
         * @throws Exception
         * @return string
         */
        function random_bytes($length)
        {
            unset($length); // Suppress "variable not used" warnings.
            throw new Exception(
                'There is no suitable CSPRNG installed on your system'
            );
            return '';
        }
    }
}

if (!is_callable('random_int')) {
    require_once $RandomCompatDIR.DIRECTORY_SEPARATOR.'random_int.php';
}

$RandomCompatDIR = null;

View on GitHub (pinned to b5d188cc9d)