affaan-m/ECC · error · FalError

live transport requires TASTE_FORGE_ALLOW_LIVE=1

Error message

live transport requires TASTE_FORGE_ALLOW_LIVE=1

What it means

require_live() is a safety gate: any live (network) transport — api_key, submit, upload, download — calls it first, and it raises falapi.FalError unless the process environment explicitly sets TASTE_FORGE_ALLOW_LIVE=1. This prevents accidental paid/unintended API calls; dry-run mode is the default posture.

Solutions

Export TASTE_FORGE_ALLOW_LIVE=1 in the same shell/session that runs the command (exact value '1').
Prefix the command inline: TASTE_FORGE_ALLOW_LIVE=1 python distill.py <genre>.
Verify no conflicting dry-run env var (the module's DRY_RUN_ENV) is set if live calls are intended.
If live calls are NOT intended, this error is working as designed — enable dry-run mode or stop.
In scripts/CI, set the env var at the job step level rather than relying on an interactive profile.

Example fix

// before
python distill.py cinematic  # FalError: live transport requires TASTE_FORGE_ALLOW_LIVE=1

// after
export TASTE_FORGE_ALLOW_LIVE=1   # exact value '1', not 'true'
python distill.py cinematic

Defensive patterns

Strategy: validation

Validate before calling

if os.environ.get("TASTE_FORGE_ALLOW_LIVE") != "1":
    raise SystemExit("set TASTE_FORGE_ALLOW_LIVE=1 to enable live API calls")

Type guard

null

Try / catch

try:
    falapi.submit(...)
except falapi.FalError as exc:
    if "TASTE_FORGE_ALLOW_LIVE" in str(exc):
        log.error("live mode not authorized; export TASTE_FORGE_ALLOW_LIVE=1")
    raise

Prevention

Set TASTE_FORGE_ALLOW_LIVE=1 (exact string '1', not 'true'/'yes') in the same shell as the command
Prefer dry-run mode for development and CI
Add an env-var assertion at the top of pipeline scripts that need live mode
Remember require_live gates api_key, submit, upload, and download
Check that a lingering dry-run env var isn't blocking intended live calls

When it happens

Trigger: Calling falapi.api_key(), submit(), upload(), or download() (directly or via distill in live mode) while os.environ['TASTE_FORGE_ALLOW_LIVE'] != '1' — including when the variable is unset, set to '0', 'true', or 'yes' (only the exact string '1' passes).

Common situations: Running distill.py live for the first time without opting in; setting TASTE_FORGE_ALLOW_LIVE=true (wrong value) in CI or shell profile; exporting the variable in one shell but running the script in another; dry-run env var still set forcing the gate.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

def is_dry_run() -> bool:
    """True when ``TASTE_FORGE_DRY_RUN`` is set to a truthy value.

    Read live rather than snapshotted at import so a CLI's ``--dry-run`` flag
    can enable it after this module is already imported.
    """
    return os.environ.get(DRY_RUN_ENV, "").strip().lower() in {"1", "true", "yes", "on"}


def enable_dry_run() -> None:
    """Turn on dry-run mode for this process (what ``--dry-run`` calls)."""
    os.environ[DRY_RUN_ENV] = "1"


def require_live() -> None:
    """Require explicit process-level authorization before any live transport."""
    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"

View on GitHub (pinned to 8321021c54)