What causes "distill failed: {exc}" in affaan-m/ECC?

Read the exception text after 'distill failed:' — it contains the underlying FileNotFoundError or FalError detail; fix that root cause.

affaan-m/ECC · error · SystemExit

distill failed

Error message

distill failed: {exc}

What it means

main() wraps the distill run in a try/except for FileNotFoundError and falapi.FalError and re-raises as SystemExit('distill failed: ...'). This is the CLI's top-level error handler: missing pack files or FAL API errors are converted into a single clean fatal message after credentials are checked pre-upload so a missing key costs nothing.

Solutions

Read the exception text after 'distill failed:' — it contains the underlying FileNotFoundError or FalError detail; fix that root cause.
Verify FAL_KEY is set and valid, or set the dry-run env var to run without credentials.
If live transport is intended, set TASTE_FORGE_ALLOW_LIVE=1 (see require_live).
Confirm all pack files (stills, props) exist on disk before running the command.
Check FAL API status/quotas if the error indicates request failure.

Example fix

// before
python distill.py cinematic  # SystemExit: distill failed: FalError(...)

// after
export FAL_KEY=...          # or TASTE_FORGE_DRY_RUN=1 for dry run
export TASTE_FORGE_ALLOW_LIVE=1
python distill.py cinematic

Defensive patterns

Strategy: try-catch

Validate before calling

if not os.environ.get("FAL_KEY") and not falapi.is_dry_run():
    raise SystemExit("FAL_KEY is not set; use dry-run or export FAL_KEY")

Type guard

null

Try / catch

try:
    distill(a.genre, a.root, a.max_stills, a.props)
except (FileNotFoundError, falapi.FalError) as exc:
    log.error("distill failed: %s", exc)
    raise SystemExit(1) from exc

Prevention

Pre-check credentials (as main() already does) before any upload
Set TASTE_FORGE_ALLOW_LIVE=1 deliberately when live mode is intended
Keep pack files intact between pipeline steps
Catch the underlying FalError/FileNotFoundError to surface root causes, not just 'distill failed'
Run a dry run first when testing new genres or configs

When it happens

Trigger: main() -> distill() chain raises falapi.FalError (bad/missing FAL key, tier/endpoint errors, live-transport not authorized) or FileNotFoundError (missing still/reference files) after the credential pre-check passes.

Common situations: Running with live mode but an invalid FAL API key; missing uploaded still file deleted between check and upload;FalError from use_tier or require_live propagating out of distill; network/API failure during submission.

Related errors

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

Appendix: source

Thrown at skills/taste-distillation/scripts/distill.py:514

                    help="stub every network call; no API key needed, no spend")
    ap.add_argument("--verbose", "-v", action="store_true")
    a = ap.parse_args()

    logging.basicConfig(
        level=logging.DEBUG if a.verbose else logging.INFO,
        format="%(levelname)s %(name)s: %(message)s",
    )
    if a.dry_run:
        falapi.enable_dry_run()

    try:
        # Check credentials before uploading anything, so a missing key costs
        # nothing and reports once.
        if not falapi.is_dry_run():
            falapi.api_key()
        distill(a.genre, a.root, a.max_stills, a.props)
    except (FileNotFoundError, falapi.FalError) as exc:
        raise SystemExit(f"distill failed: {exc}") from exc


if __name__ == "__main__":
    main()

View on GitHub (pinned to 8321021c54)