Skip to main content

​
Troubleshooting

Common issues and solutions when using QWED Open Responses.

​
Installation Issues

​
”No module named ‘qwed_open_responses’”

Cause: Package not installed Solution: 
pip install qwed-open-responses
For specific integrations: 
pip install qwed-open-responses[langchain]
pip install qwed-open-responses[openai]
pip install qwed-open-responses[all]

​
“ImportError: langchain not found”

Cause: Missing optional dependency Solution: 
pip install qwed-open-responses[langchain]
# or
pip install langchain langchain-openai

​
Guard Failures

​
”SchemaGuard: Missing required field”

Cause: Output doesn’t match expected schema Debug: 
from jsonschema import validate, ValidationError

try:
    validate(output, schema)
except ValidationError as e:
    print(f"Field: {e.path}")
    print(f"Error: {e.message}")
Common fixes:
  • Check field names (case-sensitive)
  • Ensure all required fields are present
  • Verify types match schema

​
”ToolGuard: Tool in blocklist”

Cause: Agent tried to call a blocked tool Debug: 
print(f"Blocked tool: {result.tool_name}")
print(f"Blocklist: {tool_guard.blocklist}")
Options:
  1. Remove tool from blocklist if safe
  2. Use whitelist instead
  3. Create exception for specific cases
# Whitelist mode
tool_guard = ToolGuard(
    whitelist=["calculator", "search", "read_file"],
    allow_unknown=False
)

​
”MathGuard: Calculation mismatch”

Cause: LLM provided wrong calculation Debug: 
result = math_guard.verify(output)
if not result.verified:
    print(f"Operation: {result.operation}")
    print(f"Expected: {result.expected}")
    print(f"Got: {result.actual}")
This is working as intended! The guard caught an LLM hallucination. Options:
  1. Return error to user
  2. Retry with corrected prompt
  3. Use QWED’s math engine directly

​
”SafetyGuard: PII detected”

Cause: Response contains personally identifiable information Patterns detected:
  • SSN: \d{3}-\d{2}-\d{4}
  • Credit Card: \d{16}
  • Email: Standard email pattern
  • Phone: Various formats
Options:
  1. Block (default): Return error
  2. Redact: Replace with [REDACTED]
  3. Custom patterns: Add your own
safety_guard = SafetyGuard(
    block_pii=False,
    redact_pii=True,
    custom_patterns=[
        r"EMPLOYEE-\d{6}",  # Internal ID
    ]
)

​
”StateGuard: Invalid transition”

Cause: Trying to move to invalid state Debug: 
print(f"From: {from_state}")
print(f"To: {to_state}")
print(f"Valid transitions: {state_guard.valid_transitions[from_state]}")
Fix: Review your state machine definition.

​
Integration Issues

​
LangChain callback not triggering

Check callback is added: 
# Wrong
executor = AgentExecutor(agent=agent, tools=tools)

# Right
executor = AgentExecutor(
    agent=agent,
    tools=tools,
    callbacks=[QWEDCallbackHandler(...)]  # Must include!
)
Check tool is being called: 
callback = QWEDCallbackHandler(
    log_verifications=True,  # Enable logging
    guards=[...]
)

​
OpenAI wrapper not verifying

Check you’re using VerifiedOpenAI: 
# Wrong - uses standard client
from openai import OpenAI
client = OpenAI()

# Right - uses verified wrapper
from qwed_open_responses.middleware.openai_sdk import VerifiedOpenAI
client = VerifiedOpenAI(guards=[...])
Check tool_choice is set: 
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    tools=tools,
    tool_choice="auto"  # Must enable tools
)

​
Guards not being applied

Check guard order: 
# Guards run in order
verifier = ResponseVerifier(guards=[
    SchemaGuard(schema),  # First
    ToolGuard(blocklist), # Second
    SafetyGuard(),        # Last
])
Check guard is configured: 
# Empty blocklist won't block anything
tool_guard = ToolGuard(blocklist=[])  # Does nothing!

# Fix
tool_guard = ToolGuard(blocklist=["dangerous_tool"])

​
Performance Issues

​
Verification is slow

Reduce guards: 
# Only essential guards
verifier = ResponseVerifier(guards=[
    ToolGuard(blocklist),  # Fast
    # Skip MathGuard for non-math outputs
])
Cache schemas: 
# Parse schema once
from functools import lru_cache

@lru_cache
def get_schema_guard(schema_name):
    return SchemaGuard(schema=SCHEMAS[schema_name])

​
Too many false positives

Tune PII patterns: 
safety_guard = SafetyGuard(
    pii_patterns=[
        r"\b\d{3}-\d{2}-\d{4}\b",  # Only SSN, not dates
    ]
)
Adjust tolerance: 
math_guard = MathGuard(tolerance=0.01)  # Allow 1 cent difference

​
Common Errors Reference

ErrorGuardCauseFix
”Missing required field”SchemaOutput missing fieldCheck schema
”Tool in blocklist”ToolDangerous tool calledReview blocklist
”Calculation mismatch”MathLLM math wrongThis is intentional!
”PII detected”SafetySSN/email in outputRedact or edit prompt
”Invalid transition”StateBad state flowFix state machine
”Budget exceeded”SafetyToo many callsIncrease limit
”Argument type error”ArgumentWrong typeFix tool schema

​
Getting Help

  1. GitHub Issues: github.com/QWED-AI/qwed-open-responses/issues
  2. Documentation: docs.qwedai.com/open-responses
  3. Examples: GitHub Examples