ValidatorNotFoundError
guardrails.validators.ValidatorNotFoundError
Stack trace
guardrails.validators.ValidatorNotFoundError: Validator 'toxic_language' not found in hub. Available validators: [list of installed validators]. Run `guardrails hub install toxic_language` to add it.
Why it happens
Guardrails validators are modular components stored in the Guardrails Hub. When you reference a validator by name (e.g., 'toxic_language') in Guard.use() or Guard.from_pydantic(), Guardrails looks for it in your local cache. If it's not cached, it tries to download from the hub. This fails when: (1) the validator name is misspelled or doesn't exist in the hub, (2) the hub CLI install command wasn't run beforehand, (3) network access to hub.guardrailsai.com is blocked, or (4) your Guardrails installation is out of sync with the hub registry.
Detection
Before calling guard.validate() or guard.use(), verify the validator exists locally by running `guardrails hub list` to see installed validators. Check hub.guardrailsai.com/validators for the exact validator name you need. Add logging to capture the validator name and available validators before the Guard.use() call.
Causes & fixes
Validator name is misspelled or doesn't exist in the Guardrails Hub
Run `guardrails hub list` to see all available validators, then check hub.guardrailsai.com/validators for the correct spelling and exact name. Use the canonical validator identifier (e.g., 'guardrails/toxic_language' not 'toxic_language' alone if namespaced).
Validator installed via hub CLI but Guard is looking in wrong namespace or cache location
Run `guardrails hub install toxic_language --force` to reinstall the validator and refresh the local cache. Then verify with `guardrails hub list | grep toxic_language` before using it in code.
Network access to hub.guardrailsai.com is blocked, preventing automatic download
Check firewall/proxy settings. If offline, pre-install validators on a connected machine with `guardrails hub install <validator_name>`, then sync the ~/.guardrails/validators directory to your offline environment.
Using old Guardrails API (pre-0.5) with new hub syntax, or vice versa
Ensure guardrails-ai>=0.5.0 is installed. If upgrading from <0.5, reinstall all validators with `guardrails hub install <name>`: old cache paths changed in 0.5.
Code: broken vs fixed
from guardrails import Guard
from guardrails.hub import ToxicLanguage
import os
# This fails if ToxicLanguage validator isn't installed in hub
try:
guard = Guard().use(ToxicLanguage, on_fail='exception') # ERROR: validator not found
result = guard.validate('some text')
except Exception as e:
print(f'Error: {e}')from guardrails import Guard
from guardrails.hub import ToxicLanguage
import os
import subprocess
# Install validator from hub if not already present
try:
# Ensure validator is installed first
result = subprocess.run(
['guardrails', 'hub', 'install', 'guardrails/toxic_language'],
capture_output=True, timeout=30
)
if result.returncode != 0:
print(f'Hub install warning: {result.stderr.decode()}')
except Exception as install_err:
print(f'Warning: Could not auto-install from hub: {install_err}')
# Now Guard.use() can find it in local cache
try:
guard = Guard().use(ToxicLanguage, on_fail='exception')
result = guard.validate('some text')
print(f'Validation passed: {result}')
except Exception as e:
print(f'Validation error: {e}')Workaround
If you cannot run the hub CLI in your environment, manually download the validator Python file from hub.guardrailsai.com, place it in ~/.guardrails/validators/, and import it directly: `from guardrails.validators import ToxicLanguage` (if available as a local module). Alternatively, define a custom validator inline using `Guard.use_many([Guard.from_pydantic(...)])` with built-in validators that don't require hub downloads.
Prevention
In production, pre-install all required validators in your Docker image or deployment script using `RUN guardrails hub install <validator_name>` before the app starts. Maintain a validators.txt file listing required validators and auto-install them on app startup. Use Guard initialization checks: `if not Guard.is_validator_installed('<name>'): guardrails.hub.install('<name>')` as a startup guard.