affaan-m/ECC · error · MissingKeyError

FAL_KEY is not set. Get a key at…

Error message

FAL_KEY is not set.
  Get a key at https://fal.ai/dashboard/keys, then either:
    export FAL_KEY='...'
  or run the pipeline offline with no key and no spend:
    export {DRY_RUN_ENV}=1      (or pass --dry-run)

What it means

MissingKeyError raised by api_key() in falapi.py when FAL_KEY is absent from the environment after live mode has been opted in. The library refuses to make any live fal.ai API call (submit or upload) without a credential, and deliberately never logs the key value. It also advertises the offline --dry-run path as a no-spend alternative.

Solutions

Get a key at https://fal.ai/dashboard/keys and run: export FAL_KEY='...'
Load the key from .env in the shell or process environment before running the pipeline
Run offline with no spend: export the DRY_RUN_ENV variable to 1 or pass --dry-run
In CI, add FAL_KEY as a repository/environment secret and expose it to the job

Example fix

// before
$ python pipeline.py            # MissingKeyError: FAL_KEY is not set.
// after
$ export FAL_KEY='<key from https://fal.ai/dashboard/keys>'
$ python pipeline.py   # or: export FAL_DRY_RUN=1 to run offline

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.environ.get("FAL_KEY", "").strip():
    raise SystemExit("FAL_KEY not set; export it or run with --dry-run")

Try / catch

try:
    url = falapi.submit(endpoint, payload)
except falapi.MissingKeyError:
    print("Set FAL_KEY or use --dry-run for offline mode")

Prevention

Set FAL_KEY in your shell profile or .env and source it before runs
Check `os.environ.get("FAL_KEY")` at script startup, fail fast
In CI, configure FAL_KEY as a secret injected into the environment
Use --dry-run / DRY_RUN_ENV=1 when you don't need live calls

When it happens

Trigger: Calling submit() or upload() (directly or via text_to_image, image_to_3d, vlm_describe, etc.) in live mode while os.environ has no FAL_KEY (or only whitespace).

Common situations: Fresh clone where .env was not sourced; CI job without the secret configured; running in a new shell after exporting the key only in another terminal; typo'd variable name (FAL_API_KEY).

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/e4c5c1dad7cdabca. Report an issue: GitHub.

Appendix: source

Thrown at skills/taste-distillation/scripts/taste/falapi.py:199

    if os.environ.get("TASTE_FORGE_ALLOW_LIVE") != "1":
        raise FalError("live transport requires TASTE_FORGE_ALLOW_LIVE=1")


def safe_url(url: str) -> str:
    """Log only origin: paths, queries and userinfo can carry signed secrets."""
    try:
        parsed = urllib.parse.urlsplit(url)
        return f"{parsed.scheme}://{parsed.hostname or '[invalid-host]'}"
    except ValueError:
        return "[invalid-url]"


def api_key() -> str:
    """Return ``FAL_KEY`` after live opt-in. Never logs the value."""
    require_live()
    key = os.environ.get("FAL_KEY", "").strip()
    if not key:
        raise MissingKeyError(
            "FAL_KEY is not set.\n"
            "  Get a key at https://fal.ai/dashboard/keys, then either:\n"
            "    export FAL_KEY='...'\n"
            "  or run the pipeline offline with no key and no spend:\n"
            f"    export {DRY_RUN_ENV}=1      (or pass --dry-run)"
        )
    return key


def _fal():
    """Import ``fal_client`` lazily so dry runs work even if it is absent."""
    try:
        import fal_client  # noqa: PLC0415 - deliberate lazy import
    except ImportError as exc:  # pragma: no cover - environment dependent
        raise FalError(
            "the 'fal_client' package is required for live calls: pip install fal-client"
        ) from exc
    return fal_client

View on GitHub (pinned to 8321021c54)