infiniflow/ragflow · error · ValueError

Missing Google Drive credentials in environment variables

Error message

Missing Google Drive credentials in environment variables

What it means

Raised by get_credentials_from_env when neither GOOGLE_OAUTH_CREDENTIALS_JSON_STR (oauth=True) nor GOOGLE_SERVICE_ACCOUNT_JSON_STR (oauth=False) is present in the process environment. The function reads credentials exclusively from os.environ, so an unset or empty variable triggers a KeyError that is converted into this ValueError. It fires before any Google API call is made, during connector credential resolution.

Source

Thrown at common/data_source/google_util/util.py:167

            logging.exception("Error executing request:")
            raise e
    except (TimeoutError, socket.timeout) as error:
        logging.warning(
            "Timed out executing Google API request; retrying with backoff. Details: %s",
            error,
        )
        results = retrieval_function()
    return results


def get_credentials_from_env(email: str, oauth: bool = False, source="drive") -> dict:
    try:
        if oauth:
            raw_credential_string = os.environ["GOOGLE_OAUTH_CREDENTIALS_JSON_STR"]
        else:
            raw_credential_string = os.environ["GOOGLE_SERVICE_ACCOUNT_JSON_STR"]
    except KeyError:
        raise ValueError("Missing Google Drive credentials in environment variables")

    try:
        credential_dict = json.loads(raw_credential_string)
    except json.JSONDecodeError:
        raise ValueError("Invalid JSON in Google Drive credentials")

    if oauth and source == "drive":
        credential_dict = ensure_oauth_token_dict(credential_dict, DocumentSource.GOOGLE_DRIVE)
    else:
        credential_dict = ensure_oauth_token_dict(credential_dict, DocumentSource.GMAIL)

    refried_credential_string = json.dumps(credential_dict)

    DB_CREDENTIALS_DICT_TOKEN_KEY = "google_tokens"
    DB_CREDENTIALS_DICT_SERVICE_ACCOUNT_KEY = "google_service_account_key"
    DB_CREDENTIALS_PRIMARY_ADMIN_KEY = "google_primary_admin"
    DB_CREDENTIALS_AUTHENTICATION_METHOD = "authentication_method"

View on GitHub (pinned to 554fb1133a)

Solutions

Export the correct variable: set GOOGLE_OAUTH_CREDENTIALS_JSON_STR to the JSON string of the OAuth client/token document when oauth=True, or GOOGLE_SERVICE_ACCOUNT_JSON_STR to the service-account JSON when oauth=False.
Verify the variable is visible to the same process that runs the connector: print os.environ keys (names only) or check the systemd unit / compose service environment block.
Check for name typos against the exact keys read in common/data_source/google_util/util.py:161-165.
If credentials are stored per-tenant in a DB, confirm the code path that should inject them into the environment actually ran before this call.

Example fix

# before
export GOOGLE_SERVICE_ACCOUNT_JSON=   # empty/unset -> ValueError
python -c "from common.data_source.google_util.util import get_credentials_from_env; get_credentials_from_env('a@b.com')"

# after
export GOOGLE_SERVICE_ACCOUNT_JSON_STR="$(cat /path/to/service_account.json)"
python -c "from common.data_source.google_util.util import get_credentials_from_env; get_credentials_from_env('a@b.com')"

Defensive patterns

Strategy: validation

Validate before calling

import os

REQUIRED = {
    True: "GOOGLE_OAUTH_CREDENTIALS_JSON_STR",
    False: "GOOGLE_SERVICE_ACCOUNT_JSON_STR",
}

def google_env_credentials_present(oauth: bool) -> bool:
    return bool(os.environ.get(REQUIRED[oauth]))

Try / catch

from common.data_source.google_util.util import get_credentials_from_env

try:
    creds = get_credentials_from_env(email, oauth=True)
except ValueError as e:
    if 'Missing Google Drive credentials' in str(e):
        raise RuntimeError('Environment not provisioned for Google connector') from e
    raise

Prevention

Fail fast at process start: assert the required env var names exist before spawning connector tasks.
Keep env var names in one constant module and reference it everywhere instead of retyping the literal key.
Add a pre-deploy check that diffs required env keys against the target environment.

When it happens

Trigger: Calling get_credentials_from_env(email, oauth=True) without GOOGLE_OAUTH_CREDENTIALS_JSON_STR exported, or with oauth=False without GOOGLE_SERVICE_ACCOUNT_JSON_STR. Typical when running a Google Drive or Gmail connector task in a worker process whose environment was not populated from the credential store.

Common situations: Deploying to a new environment (container, cron, CI) and forgetting to copy the .env entries; env vars set in the shell but lost because the worker runs under a different user, systemd unit, or docker-compose service; variable name typo (e.g. GOOGLE_SERVICE_ACCOUNT_JSON vs GOOGLE_SERVICE_ACCOUNT_JSON_STR).

Related errors

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