High severity intermediate · Fix: 15-45 min

DeprecationWarning: Rail XML format is deprecated

guardrails.exceptions.GuardrailsDeprecationWarning

What this error means
Guardrails-ai has deprecated the Rail XML format for defining Guards in favor of Python-based Guard definitions with validators and Pydantic models.

Stack trace

traceback
DeprecationWarning: Rail XML format is deprecated as of guardrails-ai 0.5.0. Use Guard.from_pydantic() or Guard() with Python validators instead. Support for Rail XML will be removed in version 1.0.0. (guardrails/core/guard.py:142)
QUICK FIX
Replace Guard.from_rail('file.rail') with Guard.from_pydantic(YourModel) and define validators as Python functions with @register_validator decorator.

Why it happens

Guardrails-ai transitioned from Rail XML (a custom domain-specific language) to native Python definitions to improve developer experience, reduce cognitive overhead, and enable better type checking and IDE support. Rail XML files are harder to version control, debug, and integrate with modern Python tooling. The library now recommends defining Guards directly in Python using Pydantic models, dataclasses, and validator functions, which are more Pythonic and maintainable.

Detection

Look for .rail files in your codebase or calls to Guard.from_rail_string() or Guard.from_rail(). When you run guardrails-ai 0.5+, deprecation warnings will appear in stderr during Guard initialization. Monitor your CI/CD logs for DeprecationWarning messages containing 'Rail XML format is deprecated'.

Causes & fixes

1

Loading a Guard from a .rail XML file using Guard.from_rail() or Guard.from_rail_string()

✓ Fix

Replace Guard.from_rail('path/to/schema.rail') with Guard.from_pydantic(YourPydanticModel) or Guard() initialized with validators. Define your schema using Pydantic models instead of XML.

2

Inline Rail XML passed directly to Guard initialization as a string

✓ Fix

Convert the Rail XML schema definition to a Pydantic model or dataclass, then pass it to Guard.from_pydantic(). Use guardrails validators like @register_validator to replace Rail validators.

3

Legacy guardrails workflow that relied on Rail XML for prompt templating and variable substitution

✓ Fix

Replace Rail XML variable syntax with Python f-strings or string.format(). Use Guard.format_prompt() with keyword arguments instead of Rail XML placeholders.

4

Using third-party Rail XML schemas from guardrails hub without Python equivalents

✓ Fix

Check if validators exist in guardrails.hub with Python-based definitions (e.g., ValidJson, ToxicLanguage). Use Guard().use(ValidJson) instead of importing Rail XML.

Code: broken vs fixed

Broken - triggers the error
python
import os
from guardrails import Guard

# BROKEN: Using deprecated Rail XML format (guardrails-ai 0.4.x)
guard = Guard.from_rail_string("""
<rail version="0.1">
  <output>
    <string name="email" description="User email"/>
    <string name="name" description="User name"/>
  </output>
  <validators>
    <validator name="valid_email" on-fail="exception"/>
  </validators>
</rail>
""")

response = guard.validate("user@example.com")
print(response)
Fixed - works correctly
python
import os
from pydantic import BaseModel, EmailStr, field_validator
from guardrails import Guard, register_validator, ValidationError

# FIXED: Using Python-based Guard definition (guardrails-ai 0.5+)
class UserOutput(BaseModel):
    """User data schema."""
    email: EmailStr  # Built-in email validation via Pydantic
    name: str
    
    @field_validator('name')
    @classmethod
    def name_not_empty(cls, v):
        if not v or len(v.strip()) == 0:
            raise ValueError('Name cannot be empty')
        return v

# Create Guard from Pydantic model instead of Rail XML
guard = Guard.from_pydantic(UserOutput)

try:
    response = guard.validate({"email": "user@example.com", "name": "John Doe"})
    print(f"Validation passed: {response.validated_output}")
except ValidationError as e:
    print(f"Validation failed: {e}")
Replaced Guard.from_rail_string() with Guard.from_pydantic() using a Pydantic BaseModel, moved validators to Python decorators (@field_validator), and caught guardrails ValidationError instead of relying on Rail XML exception handling.

Workaround

If you cannot immediately migrate from Rail XML, continue using guardrails-ai 0.4.x which still supports Rail XML fully. However, this is a temporary measure: plan a migration to Python-based Guards before guardrails-ai 1.0.0 is released. Alternatively, suppress deprecation warnings with `import warnings; warnings.filterwarnings('ignore', category=DeprecationWarning)` while you refactor (not recommended for production).

Prevention

1. Always define Guards using Python: leverage Pydantic models, dataclasses, or plain Python validators. 2. Use type hints and IDE autocomplete by working in native Python instead of XML. 3. Version your Guard definitions in Python code, not in separate .rail files: easier to diff and review. 4. Adopt guardrails validators from guardrails.hub that are already Python-native (ValidJson, ToxicLanguage, etc.). 5. In CI/CD pipelines, set Python warnings to error mode (`warnings.simplefilter('error', DeprecationWarning)`) to catch deprecated Guard patterns early.

Python 3.9+ · guardrails-ai >=0.5.0 · tested on 0.5.x
Verified 2026-04
Verify ↗

Community Notes

No notes yetBe the first to share a version-specific fix or tip.