infiniflow/ragflow · error · ValueError

Encryption key not provided and RAGFLOW_CRYPTO_KEY environme

Error message

Encryption key not provided and RAGFLOW_CRYPTO_KEY environment variable not set

What it means

ValueError from CryptoUtils.__init__ in common/crypto_utils.py:257-263. The constructor requires an encryption key either from the explicit `key` argument or from the RAGFLOW_CRYPTO_KEY environment variable; if neither is present it refuses to construct an instance with no key rather than silently using an empty/insecure key. This is raised right after the algorithm check, so a bad algorithm surfaces first.

Source

Thrown at common/crypto_utils.py:259

    """Cryptographic utility class, using factory pattern to create cryptographic algorithm instances"""

    # Supported cryptographic algorithms mapping
    SUPPORTED_ALGORITHMS = {"aes-128-cbc": AES128CBC, "aes-256-cbc": AES256CBC, "sm4-cbc": SM4CBC}

    def __init__(self, algorithm="aes-256-cbc", key=None, iv=None):
        """
        Initialize cryptographic utility

        Args:
            algorithm: Cryptographic algorithm, default is aes-256-cbc
            key: Encryption key, uses RAGFLOW_CRYPTO_KEY environment variable if None
            iv: Initialization vector, automatically generated if None
        """
        if algorithm not in self.SUPPORTED_ALGORITHMS:
            raise ValueError(f"Unsupported algorithm: {algorithm}")

        if not key:
            raise ValueError("Encryption key not provided and RAGFLOW_CRYPTO_KEY environment variable not set")

        # Create cryptographic algorithm instance
        self.algorithm_name = algorithm
        self.crypto = self.SUPPORTED_ALGORITHMS[algorithm](key=key, iv=iv)

    def encrypt(self, data):
        """
        Encrypt data

        Args:
            data: Data to encrypt (bytes)

        Returns:
            Encrypted data (bytes)
        """
        # import time
        # start_time = time.time()
        encrypted = self.crypto.encrypt(data)

View on GitHub (pinned to 554fb1133a)

Solutions

Export RAGFLOW_CRYPTO_KEY in the service environment (docker-compose environment:, systemd Environment=, or shell profile).
Or pass key= explicitly at construction time from your secret store.
Verify with a preflight check (e.g. print/ assert presence of the env var) before starting the app so failure is obvious at deploy time.

Example fix

# before
crypto = CryptoUtils()  # env var missing
# after (docker-compose.yml)
environment:
  - RAGFLOW_CRYPTO_KEY=${RAGFLOW_CRYPTO_KEY}
# or in code
crypto = CryptoUtils(key=os.environ["RAGFLOW_CRYPTO_KEY"])

Defensive patterns

Strategy: validation

Validate before calling

import os
key = os.environ.get("RAGFLOW_CRYPTO_KEY")
if not key:
    raise RuntimeError("RAGFLOW_CRYPTO_KEY not set — cannot initialize encryption")

Type guard

def has_crypto_key(key: str | None = None) -> bool:
    return bool(key or os.environ.get("RAGFLOW_CRYPTO_KEY"))

Try / catch

try:
    cu = CryptoUtils(key=key)
except ValueError as e:
    if "RAGFLOW_CRYPTO_KEY" in str(e):
        raise RuntimeError("Deployment misconfigured: set RAGFLOW_CRYPTO_KEY") from e
    raise

Prevention

Declare RAGFLOW_CRYPTO_KEY in docker-compose/systemd/CI environment specs.
Fail at deploy time with a preflight env check, not lazily at first encryption.
Source secrets from a secret manager into the env rather than hardcoding keys.

When it happens

Trigger: Constructing CryptoUtils() (or subclass) without key= while RAGFLOW_CRYPTO_KEY is unset in the process environment — e.g. a new deployment, a shell session without the exported var, cron/systemd units missing Environment=, or docker containers missing -e RAGFLOW_CRYPTO_KEY.

Common situations: Fresh installs following docs that omit the env var; running under systemd/supervisor where the interactive shell's exports are absent; CI pipelines lacking the secret; docker-compose file missing the environment entry.

Related errors

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/2bdfb1388e42871d. Report an issue: GitHub.