Troubleshooting Guide¶
This guide helps you diagnose and resolve common issues when working with SAM and SOPs.
Quick Diagnostics¶
Before diving into specific issues, run these quick checks:
# Check system status
make status
# Validate your SOP
make validate-sop FILE=your-sop.yaml
# Check deployment
ls -la .local/s3/forms/sops/
# Test CLAIRE connection
curl http://localhost:3000/claire/api/health
Common Issues and Solutions¶
Configuration Issues¶
Missing Configuration Files¶
Symptoms:
Error: “Config file not found”
Services won’t start
Authentication errors
Solutions:
Verify config files exist:
ls -la infra/.config/ # Should see at minimum: webapp/, lambda/
If missing, copy from examples:
cp -r infra/example-.config/* infra/.config/
See Frontend Configuration Guide for help with customizing the configs for your environment
Run setup to create local directories:
make setup-local ENV=dev
Check environment variable:
echo $ENV # Should be "dev" for local development
For more details, see:
Frontend Configuration Guide - Config structure and customization
General Configuration Guide - Overall configuration management
Editor Issues¶
SAM Editor Not Loading¶
Symptoms:
Blank page or loading spinner
JavaScript errors in console
Components not rendering
Solutions:
Clear browser cache:
# Force refresh Ctrl+Shift+R (Windows/Linux) Cmd+Shift+R (Mac)
Check browser console:
Press F12 to open developer tools
Look for red error messages
Common errors: network failures, missing dependencies
Verify services running:
# Check if SAM is running ps aux | grep sam # Restart SAM make restart-sam
Check network:
Verify localhost:3000 is accessible
Check firewall settings
Ensure no port conflicts
Form Builder Not Working¶
Symptoms:
Can’t add fields
Drag and drop not functioning
UI elements unresponsive
Solutions:
Check schema registry:
// In browser console console.log(window.__SCHEMA_REGISTRY__);
Reload schemas:
make build-schemas make restart-sam
Browser compatibility:
Use Chrome, Firefox, or Edge (latest versions)
Disable browser extensions that might interfere
Autosave Not Working¶
Symptoms:
Changes lost on refresh
No autosave indicator
Drafts not appearing
Solutions:
Check local storage:
// In browser console localStorage.getItem('sam-autosave');
Clear corrupted data:
localStorage.removeItem('sam-autosave'); location.reload();
Verify permissions:
Browser must allow local storage
Check privacy/security settings
Validation Issues¶
Validation Never Completes¶
Symptoms:
Validation spinner runs indefinitely
No error or success message
Browser becomes unresponsive
Solutions:
Check SOP size:
Very large SOPs (>1000 fields) may timeout
Split into smaller SOPs if needed
Look for circular references:
# BAD: Circular reference taskA: children: [$ref: '#/taskB'] taskB: children: [$ref: '#/taskA']
Validate YAML syntax first:
# Use external validator yamllint your-sop.yaml
False Validation Errors¶
Symptoms:
Valid fields marked as invalid
Schema version mismatch errors
Type errors on correct types
Solutions:
Update schema cache:
make clean-cache make build-schemas
Check schema version:
# Ensure using correct version '$schema': 'SOPTemplateSchema/v2.0'
Verify field types:
# Common mistake: quotes on numbers ordinal: 1 # Correct ordinal: "1" # Wrong - string not number
Validation Passes But Form Broken¶
Symptoms:
SOP validates successfully
Form doesn’t render in CLAIRE
Missing tabs or fields
Solutions:
Check hierarchical structure:
# Correct structure taskgroups: - children: # Must have children - '@type': Task # Must be Task type
Verify parent-child relationships:
All children must reference valid parents
No orphaned elements
Test minimal version:
Start with basic structure
Add complexity gradually
Identify breaking change
Deployment Problems¶
SOP Not Appearing in CLAIRE¶
Symptoms:
Deployed SOP not in list
404 error when accessing
Old version still showing
Solutions:
Verify deployment location:
# Check file exists ls -la .local/s3/forms/sops/your-sop.yaml # Check file permissions chmod 644 .local/s3/forms/sops/your-sop.yaml
Clear CLAIRE cache:
# Restart CLAIRE make restart-claire # Or clear cache manually rm -rf .claire-cache/*
Check filename:
Must end with
.yamlor.ymlNo spaces in filename
Case-sensitive on Linux
Verify YAML structure:
# Test parse python -c "import yaml; yaml.safe_load(open('your-sop.yaml'))"
Permission Denied Errors¶
Symptoms:
Can’t write to S3
Access denied messages
403 Forbidden errors
Solutions:
Local permissions:
# Fix local directory permissions chmod -R 755 .local/s3/ chown -R $USER:$USER .local/s3/
AWS permissions:
# Check AWS credentials aws sts get-caller-identity # Test S3 access aws s3 ls s3://your-bucket/
IAM policies:
Verify user has s3:PutObject permission
Check bucket policies
Review IAM role assignments
Version Conflicts¶
Symptoms:
Wrong version deployed
Multiple versions present
Version rollback not working
Solutions:
Clean deployment:
# Remove all versions rm .local/s3/forms/sops/your-sop*.yaml # Deploy specific version cp your-sop-v1.0.0.yaml .local/s3/forms/sops/your-sop.yaml
Version tracking:
# List all versions ls -la .local/s3/forms/sops/ | grep your-sop # Check current version grep "version:" .local/s3/forms/sops/your-sop.yaml
Rendering Issues¶
Fields Not Displaying¶
Symptoms:
Fields defined but not visible
Empty tabs or sections
Missing input elements
Solutions:
Check type property:
# Field MUST have type to render - id: my_field '@type': Field type: "string" # Required for rendering
Verify hierarchy:
taskgroups: - children: # Task groups need children - '@type': Task children: # Tasks need children - '@type': Field
Check UI config:
ui_config: hidden: false # Ensure not hidden component_type: "field" # Correct type
Tabs Not Working¶
Symptoms:
Tabs not clickable
Content not switching
All tabs show same content
Solutions:
Unique IDs required:
# Each task needs unique ID - id: task_1 # Must be unique - id: task_2 # Must be unique
Ordinal values:
# Set ordinal for tab order - ordinal: 1 - ordinal: 2
Parent references:
Tasks must reference parent taskgroup
Check for broken references
Styling Issues¶
Symptoms:
Components look broken
Inconsistent styling
Missing icons or colors
Solutions:
Check CSS loading:
// In browser console document.styleSheets.length > 0
Verify UI config:
ui_config: variant: "default" # Use valid variant className: "valid-class" # Check class exists
Browser compatibility:
Update to latest browser version
Check browser-specific CSS issues
Performance Issues¶
Slow Form Loading¶
Symptoms:
Long load times (>5 seconds)
Browser freezing
Memory warnings
Solutions:
Reduce complexity:
Limit fields per tab (<50)
Minimize nested structures
Split large SOPs
Optimize validation:
Simplify regex patterns
Reduce cross-field validations
Use async validation
Browser optimization:
// Clear memory if (window.gc) window.gc();
Memory Leaks¶
Symptoms:
Browser memory usage growing
Page becomes unresponsive
Crashes after extended use
Solutions:
Monitor memory:
Use Chrome DevTools Memory Profiler
Look for detached DOM nodes
Check for event listener leaks
Clear unused data:
// Manual cleanup window.__CLEAR_CACHE__();
Restart periodically:
Refresh page every few hours
Clear browser cache regularly
Data Issues¶
Lost Form Data¶
Symptoms:
Entered data disappears
Drafts not saving
Submission failures
Solutions:
Check autosave:
// View autosave data JSON.parse(localStorage.getItem('claire-drafts'));
Manual backup:
// Export current form data copy(JSON.stringify(window.__FORM_DATA__));
Recovery options:
Check browser history
Look for temp files
Review server logs
Validation Errors on Submit¶
Symptoms:
Can’t submit valid data
Required fields marked empty
Type mismatch errors
Solutions:
Check field values:
// Inspect form data console.log(document.querySelector('form').elements);
Clear and retry:
Clear field and re-enter
Check for invisible characters
Verify correct format
Debug validation:
// Enable validation debugging window.__DEBUG_VALIDATION__ = true;
Debug Tools and Commands¶
Browser Console Commands¶
// Get current SOP
window.__CURRENT_SOP__
// View form state
window.__FORM_STATE__
// Check validation errors
window.__VALIDATION_ERRORS__
// Export debug info
window.__EXPORT_DEBUG__()
// Clear all caches
window.__CLEAR_ALL__()
// Enable verbose logging
window.__VERBOSE__ = true
Command Line Tools¶
# Check system health
make health-check
# Run diagnostics
make diagnose
# View logs
tail -f logs/sam.log
tail -f logs/claire.log
# Test specific SOP
make test-sop FILE=your-sop.yaml
# Full system reset
make clean-all && make setup
Log File Locations¶
logs/
├── sam.log # SAM editor logs
├── claire.log # CLAIRE runtime logs
├── validation.log # Validation errors
├── deployment.log # Deployment history
└── error.log # System errors
Getting Help¶
Before Asking for Help¶
Gather information:
Error messages (exact text)
Browser console output
SOP YAML file
Steps to reproduce
Try basic fixes:
Clear cache
Restart services
Validate YAML
Check examples
Document issue:
What you expected
What actually happened
What you’ve tried
Support Channels¶
Documentation:
This troubleshooting guide
Community:
GitHub Issues
Discussion forums
Stack Overflow
Direct Support:
System administrator
Development team
Help desk ticket
Reporting Bugs¶
Include in bug reports:
## Bug Report
**Environment:**
- OS: [Windows/Mac/Linux]
- Browser: [Chrome/Firefox/Safari] [version]
- SAM Version: [version]
- CLAIRE Version: [version]
**Description:**
[What happened]
**Expected Behavior:**
[What should happen]
**Steps to Reproduce:**
1. [First step]
2. [Second step]
3. [Error occurs]
**Error Messages:**
[Paste exact error]
**SOP YAML:**
```yaml
[Paste relevant section]
Screenshots: [Attach if applicable]
## Prevention Tips
### Best Practices
1. **Regular maintenance:**
- Update regularly
- Clear cache weekly
- Archive old SOPs
- Monitor logs
2. **Development workflow:**
- Test locally first
- Validate frequently
- Use version control
- Document changes
3. **System health:**
- Monitor disk space
- Check memory usage
- Review error logs
- Update dependencies
### Common Mistakes to Avoid
❌ **Don't:**
- Edit production directly
- Skip validation
- Use special characters in IDs
- Create circular references
- Ignore error messages
- Deploy without testing
✅ **Do:**
- Test thoroughly
- Keep backups
- Follow naming conventions
- Validate before deploying
- Monitor after deployment
- Document everything
## Summary
Most issues can be resolved by:
1. **Validating your SOP**
2. **Clearing caches**
3. **Restarting services**
4. **Checking logs**
5. **Following examples**
When in doubt, start with a minimal working example and gradually add complexity to identify the issue.
## Next Steps
- [Review examples](examples.md)
- [Check schema reference](schema-reference.md)
- [Read deployment guide](deployment.md)
- [Return to main documentation](index.md)