calesthio/OpenMontage · error · RuntimeError

GOOGLE_APPLICATION_CREDENTIALS is not set or points to a mis

Error message

GOOGLE_APPLICATION_CREDENTIALS is not set or points to a missing file; cannot use service-account authentication.

What it means

RuntimeError raised when the GOOGLE_APPLICATION_CREDENTIALS environment variable is unset or points to a path that does not exist on disk. The service-account flow needs a JSON key file, and this check runs before any network call so misconfiguration is reported immediately rather than as an opaque Google auth error.

Source

Thrown at tools/google_credentials.py:118

    Raises:
        RuntimeError: if ``google-auth`` is missing or the credentials cannot
            be loaded/refreshed — with a message the agent can surface verbatim.
    """
    if scopes is None:
        scopes = [CLOUD_PLATFORM_SCOPE]

    try:
        from google.auth.transport.requests import Request
        from google.oauth2 import service_account
    except ImportError as exc:  # pragma: no cover - depends on optional dep
        raise RuntimeError(
            "Service-account auth requires the 'google-auth' package. "
            "Install it with: pip install google-auth"
        ) from exc

    path = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
    if not path or not os.path.exists(path):
        raise RuntimeError(
            "GOOGLE_APPLICATION_CREDENTIALS is not set or points to a missing "
            "file; cannot use service-account authentication."
        )

    try:
        creds = service_account.Credentials.from_service_account_file(
            path, scopes=scopes
        )
        creds.refresh(Request())
    except Exception as exc:  # noqa: BLE001 - re-raised as actionable message
        raise RuntimeError(
            f"Failed to load/refresh service-account credentials from {path}: {exc}"
        ) from exc

    token = creds.token
    if not token or not isinstance(token, str):
        raise RuntimeError(
            "Service-account credentials did not yield a valid access token."

View on GitHub (pinned to 95e1c3d0ab)

Solutions

Export the variable with an absolute path: `export GOOGLE_APPLICATION_CREDENTIALS=/abs/path/service-account.json`.
Verify both conditions the code checks: `echo $GOOGLE_APPLICATION_CREDENTIALS` prints a path AND `test -f "$GOOGLE_APPLICATION_CREDENTIALS"` succeeds.
In Docker/CI, ensure the env var is passed (-e / env: block) and the key file is actually mounted/copied into the container at that path.
Use absolute paths — relative paths break when the process cwd differs.

Example fix

# before
subprocess.run(["python", "-m", "app"])  # env var not inherited -> RuntimeError

# after
import os
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = str(key_path.resolve())
assert Path(os.environ["GOOGLE_APPLICATION_CREDENTIALS"]).is_file()
subprocess.run(["python", "-m", "app"], env=os.environ)

Defensive patterns

Strategy: validation

Validate before calling

import os
from pathlib import Path

def credentials_configured() -> bool:
    path = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
    return bool(path) and Path(path).is_file()

Try / catch

try:
    token, project = get_service_account_token()
except RuntimeError as e:
    if "GOOGLE_APPLICATION_CREDENTIALS" in str(e):
        raise SystemExit("Set GOOGLE_APPLICATION_CREDENTIALS to an absolute key path") from e
    raise

Prevention

Set GOOGLE_APPLICATION_CREDENTIALS to an absolute path in service/CI definitions.
Add a preflight check for the env var + file existence before starting paid work.
Load .env files explicitly in local dev so exports are not forgotten.

When it happens

Trigger: Invoking service-account auth with GOOGLE_APPLICATION_CREDENTIALS missing from the environment (env not exported, .env not loaded, different shell/deployment context) or set to a stale/moved/typo'd file path.

Common situations: Secrets set in a local shell but not passed to Docker/systemd/CI service context; the key file moved after rotation; relative path resolved from a different working directory; variable name typo (e.g. GOOGLE_APPLICATION_CREDENTIAL).

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/adffbe6fc8184e1a. Report an issue: GitHub.