crewAIInc/crewAI · error · Exception

An error occurred while running the flow with trigger

Error message

An error occurred while running the flow with trigger: {e}

What it means

Catch-all wrapper in the flow template's run_with_trigger(). After payload validation, content_flow.kickoff({'crewai_trigger_payload': payload}) executes; any exception in the flow's start listener, crew steps, or state handling is re-raised as a generic Exception with 'An error occurred while running the flow with trigger: {e}'.

Solutions

Inspect the inner exception after the colon for the real error (KeyError on payload fields, auth failures).
Reproduce locally with the exact payload: `uv run run_with_trigger '<payload>'`.
Make the start step defensive: read trigger fields via .get() with defaults instead of direct dict access.
Ensure API keys/env are configured where the flow runs.

Example fix

# before
except Exception as e:
    raise Exception(f"An error occurred while running the flow with trigger: {e}")

# after
except Exception:
    import traceback
    traceback.print_exc()
    raise

Defensive patterns

Strategy: try-catch

Validate before calling

import os
assert os.getenv("OPENAI_API_KEY"), "API key missing for flow kickoff"

Type guard

def payload_has(payload: dict, key: str) -> bool:
    return isinstance(payload, dict) and key in payload

Try / catch

try:
    result = content_flow.kickoff({"crewai_trigger_payload": payload})
except Exception:
    logging.exception("flow trigger kickoff failed")
    raise

Prevention

Read trigger fields via .get() with defaults in start steps
Re-run with traceback printing in local main.py when debugging
Keep env vars configured identically in deploy and local environments

When it happens

Trigger: Valid JSON payload but the flow fails during kickoff: a start step expecting fields missing from the payload, LLM auth errors, or an exception in downstream flow steps.

Common situations: Flow works in normal kickoff but the trigger payload shape differs from what start() reads from state; deployment environment missing API keys; schema drift between the trigger source and flow expectations.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/c47480205b4bc44a. Report an issue: GitHub.

Appendix: source

Thrown at lib/cli/src/crewai_cli/templates/flow/main.py:85

    """
    import json
    import sys

    if len(sys.argv) < 2:
        raise Exception("No trigger payload provided. Please provide JSON payload as argument.")

    try:
        trigger_payload = json.loads(sys.argv[1])
    except json.JSONDecodeError:
        raise Exception("Invalid JSON payload provided as argument")

    content_flow = ContentFlow()

    try:
        result = content_flow.kickoff({"crewai_trigger_payload": trigger_payload})
        return result
    except Exception as e:
        raise Exception(f"An error occurred while running the flow with trigger: {e}")


if __name__ == "__main__":
    kickoff()

View on GitHub (pinned to 754d7323be)