Heuristic:Guardrails ai Guardrails Async Vs Sync Validation Mode
| Knowledge Sources | |
|---|---|
| Domains | Optimization, Debugging |
| Last Updated | 2026-02-14 12:00 GMT |
Overview
Decision framework for choosing between async and synchronous validation modes, and understanding automatic fallback behavior.
Description
Guardrails AI supports two validation execution modes: AsyncValidatorService (default) and SequentialValidatorService. The async mode runs validators concurrently using an event loop, which is faster when multiple validators are attached to a Guard. The sync mode runs validators sequentially. The mode selection is controlled by the `GUARDRAILS_RUN_SYNC` environment variable and has automatic fallback logic when an event loop conflict is detected.
Usage
Apply this heuristic when:
- You encounter event loop errors in Jupyter notebooks, async web frameworks, or nested async contexts.
- You need deterministic execution order for debugging validator interactions.
- You want to optimize throughput by understanding which mode to use.
- Streaming validation always uses sequential mode regardless of this setting.
The Insight (Rule of Thumb)
- Action: Leave `GUARDRAILS_RUN_SYNC` at default (`false`) for production. Set to `true` when running inside an existing event loop (Jupyter, FastAPI, etc.) or when debugging validator ordering issues.
- Value: `GUARDRAILS_RUN_SYNC=false` (default, async) or `GUARDRAILS_RUN_SYNC=true` (sequential).
- Trade-off: Async mode is faster for multiple validators but can conflict with existing event loops. Sync mode is slower but deterministic and compatible with all contexts.
Reasoning
The async validator service uses `asyncio.get_event_loop()` to run validators concurrently. When called from within an already-running event loop (common in Jupyter notebooks, async web frameworks like FastAPI, or testing frameworks), this raises a `RuntimeError`. The code handles this with a graceful fallback to synchronous mode, but the warning message can confuse users.
Additionally, the code uses uvloop as an optional performance optimization for the event loop when available. This only applies in async mode and only on Linux/macOS.
Key insight: Streaming validation (validate_stream) always uses SequentialValidatorService regardless of the `GUARDRAILS_RUN_SYNC` setting, because streaming inherently requires sequential processing of chunks.
Evidence from source:
Mode selection and fallback from `guardrails/validator_service/__init__.py:30-79`:
def should_run_sync():
run_sync = os.environ.get("GUARDRAILS_RUN_SYNC", "false")
bool_values = ["true", "false"]
if run_sync.lower() not in bool_values:
warnings.warn(
f"GUARDRAILS_RUN_SYNC must be one of {bool_values}! Defaulting to 'false'."
)
return run_sync.lower() == "true"
def get_loop() -> asyncio.AbstractEventLoop:
try:
loop = asyncio.get_running_loop()
except RuntimeError:
loop = None
if loop is not None:
raise RuntimeError("An event loop is already running.")
if uvloop is not None:
asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
return asyncio.get_event_loop()
Automatic fallback logic from `guardrails/validator_service/__init__.py:67-79`:
if should_run_sync():
validator_service = SequentialValidatorService(disable_tracer)
else:
try:
loop = get_loop()
validator_service = AsyncValidatorService(disable_tracer)
except RuntimeError:
warnings.warn(
"Could not obtain an event loop."
" Falling back to synchronous validation."
)
validator_service = SequentialValidatorService(disable_tracer)
Streaming always uses sequential from `guardrails/validator_service/__init__.py:104`:
sequential_validator_service = SequentialValidatorService(disable_tracer)