{"record":{"id":"2bdfb1388e42871d","repo":"infiniflow/ragflow","slug":"encryption-key-not-provided-and-ragflow-crypto-key","errorCode":null,"errorMessage":"Encryption key not provided and RAGFLOW_CRYPTO_KEY environment variable not set","messagePattern":"Encryption key not provided and RAGFLOW_CRYPTO_KEY environment variable not set","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"common/crypto_utils.py","lineNumber":259,"sourceCode":"    \"\"\"Cryptographic utility class, using factory pattern to create cryptographic algorithm instances\"\"\"\n\n    # Supported cryptographic algorithms mapping\n    SUPPORTED_ALGORITHMS = {\"aes-128-cbc\": AES128CBC, \"aes-256-cbc\": AES256CBC, \"sm4-cbc\": SM4CBC}\n\n    def __init__(self, algorithm=\"aes-256-cbc\", key=None, iv=None):\n        \"\"\"\n        Initialize cryptographic utility\n\n        Args:\n            algorithm: Cryptographic algorithm, default is aes-256-cbc\n            key: Encryption key, uses RAGFLOW_CRYPTO_KEY environment variable if None\n            iv: Initialization vector, automatically generated if None\n        \"\"\"\n        if algorithm not in self.SUPPORTED_ALGORITHMS:\n            raise ValueError(f\"Unsupported algorithm: {algorithm}\")\n\n        if not key:\n            raise ValueError(\"Encryption key not provided and RAGFLOW_CRYPTO_KEY environment variable not set\")\n\n        # Create cryptographic algorithm instance\n        self.algorithm_name = algorithm\n        self.crypto = self.SUPPORTED_ALGORITHMS[algorithm](key=key, iv=iv)\n\n    def encrypt(self, data):\n        \"\"\"\n        Encrypt data\n\n        Args:\n            data: Data to encrypt (bytes)\n\n        Returns:\n            Encrypted data (bytes)\n        \"\"\"\n        # import time\n        # start_time = time.time()\n        encrypted = self.crypto.encrypt(data)","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/crypto_utils.py#L241-L277","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\ncrypto = CryptoUtils()  # env var missing\n# after (docker-compose.yml)\nenvironment:\n  - RAGFLOW_CRYPTO_KEY=${RAGFLOW_CRYPTO_KEY}\n# or in code\ncrypto = CryptoUtils(key=os.environ[\"RAGFLOW_CRYPTO_KEY\"])","handlingStrategy":"validation","validationCode":"import os\nkey = os.environ.get(\"RAGFLOW_CRYPTO_KEY\")\nif not key:\n    raise RuntimeError(\"RAGFLOW_CRYPTO_KEY not set — cannot initialize encryption\")","typeGuard":"def has_crypto_key(key: str | None = None) -> bool:\n    return bool(key or os.environ.get(\"RAGFLOW_CRYPTO_KEY\"))","tryCatchPattern":"try:\n    cu = CryptoUtils(key=key)\nexcept ValueError as e:\n    if \"RAGFLOW_CRYPTO_KEY\" in str(e):\n        raise RuntimeError(\"Deployment misconfigured: set RAGFLOW_CRYPTO_KEY\") from e\n    raise","preventionTips":["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."],"tags":["crypto","secrets","environment","configuration"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}