SDCStudio Troubleshooting Guide

Quick Problem Resolution

Common Issues & Solutions

File Upload Issues

Upload Fails Completely

Symptoms

• File upload button doesn't respond
• Upload progress bar doesn't appear
• Error message: "Upload failed"

Quick Fixes

1. Check file size: Ensure file is under 50MB
2. Verify format: Use supported formats (CSV, Markdown, JSON, XML)
3. Clear browser cache: Refresh page or clear browser data
4. Check internet connection: Ensure stable connection

Detailed Solutions

File Size Too Large

# For CSV files, split into smaller chunks
# Use tools like:
# - Excel: Save as multiple files
# - Python: pandas.DataFrame.to_csv() with chunksize
# - Command line: split command

Unsupported Format

• Convert to CSV: Use spreadsheet applications
• Convert to Markdown: Use text editors or converters
• Check encoding: Ensure UTF-8 encoding

Browser Issues

• Update browser: Use latest Chrome, Firefox, Safari, or Edge
• Disable extensions: Temporarily disable ad blockers
• Try incognito mode: Test without extensions

Upload Stuck or Slow

Symptoms

• Upload progress bar moves slowly
• Upload appears to hang at certain percentage
• No error message, but upload never completes

Causes & Solutions

Large File Processing

• Wait longer: Large files take more time to process
• Check server status: System may be under heavy load
• Retry later: Try during off-peak hours

Network Issues

• Check connection: Verify stable internet connection
• Try different network: Switch to mobile hotspot if available
• Contact support: If issue persists

AI Processing Issues

Processing Stuck in "Analyzing Structure"

Symptoms

• Status shows "Analyzing Structure" for >5 minutes
• No progress updates
• Processing appears frozen

Quick Fixes

1. Wait longer: Phase 1 can take 1-2 minutes for large files
2. Refresh page: Check for status updates
3. Cancel and retry: Stop processing and restart

Detailed Solutions

File Complexity Issues

• Simplify file: Remove unnecessary columns or rows
• Check data quality: Ensure consistent formatting
• Reduce file size: Split into smaller files

System Load Issues

• Check system status: Look for maintenance notices
• Retry later: Wait for system load to decrease
• Contact support: If issue persists >10 minutes

Processing Stuck in "AI Enhancement"

Symptoms

• Status shows "AI Enhancement" for >10 minutes
• No progress updates
• Processing appears stuck

Quick Fixes

1. Wait longer: Phase 2 can take 3-5 minutes for complex files
2. Check file complexity: Very complex files take longer
3. Cancel and retry: Stop and restart processing

Detailed Solutions

Complex Data Issues

• Reduce complexity: Simplify data structure
• Remove special characters: Clean up unusual data
• Standardize format: Use consistent data patterns

AI Model Issues

• Check system status: AI service may be unavailable
• Retry processing: AI models occasionally fail
• Contact support: If multiple retries fail

Processing Fails with Error

Common Error Messages

"Processing failed - please try again"

• Cause: Temporary system issue or file corruption
• Solution: Wait 5 minutes, then retry upload

"File format not supported"

• Cause: Unsupported file type or corrupted file
• Solution: Convert to supported format or fix file

"AI processing timeout"

• Cause: File too complex or system overloaded
• Solution: Simplify file or retry during off-peak hours

Generation Issues

XML Generation Fails

Symptoms

• XML generation button doesn't work
• Error message: "XML generation failed"
• No XML file created

Quick Fixes

1. Ensure model is published: Unpublished models can't generate XML
2. Check XSD generation: XML depends on successful XSD generation
3. Verify model completeness: All components must be properly defined

Detailed Solutions

Model Not Published

1. Navigate to your model: Go to /app/models and click on the model
2. Click "Publish" button: Located in the top action bar (only available for unpublished models)
3. Wait for publication to complete: Watch for the status to change to "Published"
4. Generate package (One-Time Only): Click "Generate Package (One-Time Only)" to generate all export files
5. Important: This can only be done ONCE. Ensure your model is complete before generating.

XSD Generation Issues

1. Check XSD generation status
2. Resolve any validation errors
3. Regenerate XSD if needed
4. Then generate XML

Component Issues

1. Review component definitions
2. Check for missing required fields
3. Verify component relationships
4. Fix any validation errors

Schema Validation Errors

Common Validation Issues

Missing Required Elements

• Problem: Required elements not defined in schema
• Solution: Add missing elements to component definitions

Type Mismatches

• Problem: Data types don't match expected types
• Solution: Update component data types to match requirements

Constraint Violations

• Problem: Validation rules are too restrictive
• Solution: Review and adjust validation constraints

Debugging Validation Errors

1. Check error messages: Look for specific element names
2. Review component schemas: Verify element definitions
3. Test constraints: Ensure validation rules are reasonable
4. Check relationships: Verify component connections

App Generation Issues

App Generation Incomplete

Symptoms

• Generated app is missing components
• App doesn't function properly
• Error messages during generation

Quick Fixes

1. Verify model completeness: All components must be properly defined
2. Check component relationships: Ensure proper connections
3. Validate model: Resolve any validation errors

Detailed Solutions

Missing Components

1. Review component definitions
2. Check component relationships
3. Verify component types
4. Regenerate app after fixes

App Structure Issues

1. Check model organization
2. Verify cluster structure
3. Review component hierarchy
4. Fix structural issues

Generated App Doesn't Work

Common Issues

Missing Dependencies

• Problem: App missing required libraries or components
• Solution: Check generated requirements.txt and install dependencies

Configuration Issues

• Problem: App not properly configured
• Solution: Review generated configuration files

Database Issues

• Problem: Database models not properly generated
• Solution: Check generated model files and database setup

Performance Issues

Slow Processing

Causes & Solutions

Large Files

• Split files: Break large files into smaller chunks
• Optimize data: Remove unnecessary columns or rows
• Use efficient formats: CSV is faster than complex formats

Complex Data

• Simplify structure: Reduce nested relationships
• Standardize format: Use consistent data patterns
• Remove special characters: Clean up unusual data

System Load

• Check system status: Look for maintenance notices
• Retry later: Wait for system load to decrease
• Contact support: If issues persist

Memory Issues

Symptoms

• Browser becomes unresponsive
• Error messages about memory
• Processing fails with memory errors

Solutions

1. Close other tabs: Free up browser memory
2. Use smaller files: Reduce file size and complexity
3. Update browser: Use latest browser version
4. Clear cache: Clear browser cache and cookies

Data Quality Issues

Poor AI Suggestions

Symptoms

• AI suggests inappropriate components
• Component types don't match data
• Missing important relationships

Solutions

Improve Data Quality

1. Clean data: Remove errors and inconsistencies
2. Add context: Include descriptive headers and labels
3. Standardize format: Use consistent naming conventions
4. Provide examples: Include sample data rows

Enhance Metadata

1. Add descriptions: Include component descriptions
2. Use clear names: Choose descriptive component names
3. Add tags: Include relevant categorization
4. Document relationships: Explain component connections

Incorrect Type Detection

Common Issues

String vs Number

• Problem: Numbers detected as strings
• Solution: Ensure numeric columns contain only numbers

Date Format Issues

• Problem: Dates not recognized properly
• Solution: Use consistent date formats (YYYY-MM-DD recommended)

Boolean Confusion

• Problem: Boolean values not detected
• Solution: Use consistent true/false values

System Integration Issues

API Problems

Authentication Issues

• Problem: API calls fail with auth errors
• Solution: Check API keys and authentication tokens

Rate Limiting

• Problem: API calls fail with rate limit errors
• Solution: Implement proper rate limiting and retry logic

Endpoint Issues

• Problem: API endpoints not responding
• Solution: Check API documentation and endpoint URLs

Export Problems

File Download Issues

• Problem: Generated files won't download
• Solution: Check browser download settings and permissions

Format Issues

• Problem: Exported files in wrong format
• Solution: Verify export format selection and regenerate

Getting Help

Self-Service Resources

Documentation

• User Guide: Comprehensive usage instructions
• API Reference: Technical API documentation
• Examples: Sample files and use cases
• Best Practices: Recommended approaches

Community Resources

• User Forums: Community discussions and help
• Knowledge Base: Common questions and answers
• Video Tutorials: Step-by-step video guides
• Webinars: Live training sessions

Contacting Support

When to Contact Support

• System errors: Persistent technical issues
• Data loss: Important data not accessible
• Security issues: Suspected security problems
• Feature requests: New functionality suggestions

Information to Provide

• Error messages: Exact error text and codes
• Steps to reproduce: Detailed reproduction steps
• File information: File types, sizes, and formats
• System details: Browser, OS, and version information

Support Channels

• Email: support@sdcstudio.com
• Help Desk: Submit tickets through web interface
• Live Chat: Available during business hours
• Phone: Emergency support for critical issues

Prevention Tips

Best Practices

File Preparation

• Use consistent formats: Standardize data structure
• Clean data: Remove errors and inconsistencies
• Add metadata: Include descriptive information
• Test with small files: Verify process before large uploads

Model Design

• Plan structure: Design before implementation
• Use clear names: Choose descriptive component names
• Validate early: Test validation rules during creation
• Document relationships: Explain component connections

Regular Maintenance

• Review models: Periodically review and update
• Clean up: Remove unused components and models
• Update documentation: Keep documentation current
• Monitor performance: Track system usage and performance

Still having issues? Check the User Guide for detailed information, or contact support for personalized assistance.