ValueError
guardrails.guard.ValueError: Invalid on_fail action
Stack trace
Traceback (most recent call last):
File "<your_script>.py", line 42, in <module>
guard.use(ToxicLanguage, on_fail='skip')
File "<guardrails_install>/guard.py", line 287, in use
raise ValueError(f"Invalid on_fail action '{on_fail}'. Allowed actions: {', '.join(ALLOWED_ON_FAIL_ACTIONS)}")
ValueError: Invalid on_fail action 'skip'. Allowed actions: exception, filter, fix, fix_repeat, noop Why it happens
Guardrails defines a strict set of valid on_fail handlers that determine what happens when a validator fails. The on_fail parameter must be one of: 'exception' (raise error), 'filter' (remove failing output), 'fix' (attempt auto-correction), 'fix_repeat' (retry fix until valid), or 'noop' (silent pass). Passing a misspelled, deprecated, or unsupported action name causes this ValueError at Guard initialization time.
Detection
Review all Guard().use() calls in your codebase and validate on_fail parameter values against the official allowed list. Add type hints (Literal['exception'|'filter'|'fix'|'fix_repeat'|'noop']) to catch this at IDE time before runtime.
Causes & fixes
Typo in on_fail parameter name (e.g., 'skip' instead of 'noop', 'error' instead of 'exception')
Change on_fail parameter to one of: 'exception', 'filter', 'fix', 'fix_repeat', or 'noop'. Double-check spelling.
Using deprecated on_fail action from guardrails-ai v0.3 or earlier
Upgrade to guardrails-ai>=0.5.0 and map old actions: 'fix_repeat' replaces old 'auto_fix', 'noop' replaces old 'silent'.
Passing a callable or custom handler instead of a string action name
Use string literals only: on_fail='exception'. Custom error handlers use exception catching, not on_fail parameter.
on_fail parameter is None, empty string, or non-string type
Ensure on_fail is a non-empty string literal matching one of the five allowed actions. Use Literal type hints to enforce at IDE time.
Code: broken vs fixed
import os
from guardrails import Guard
from guardrails.hub import ToxicLanguage
guard = Guard()
# BUG: 'skip' is not a valid on_fail action
guard.use(ToxicLanguage, on_fail='skip')
result = guard.validate('This is a test')
print(result)import os
from guardrails import Guard
from guardrails.hub import ToxicLanguage
guard = Guard()
# FIXED: Use valid on_fail action 'noop' (silent pass) or 'exception' (raise error)
guard.use(ToxicLanguage, on_fail='exception')
result = guard.validate('This is a test')
print(f'Validation result: {result}')Workaround
Wrap Guard.use() in a try/except block and provide a fallback on_fail='noop' if the intended action is unsupported in your version. Log the exact on_fail action you intended so you can debug the version mismatch later.
Prevention
Use type hints with Literal to enforce valid on_fail values at IDE time: from typing import Literal; guard.use(validator, on_fail: Literal['exception', 'filter', 'fix', 'fix_repeat', 'noop'] = 'exception'). Validate guardrails-ai version in CI/CD pipelines to catch deprecated action deprecations before deployment.