Troubleshooting Guide

This guide will help you resolve common issues encountered when using HAI RapidUI. We've organized troubleshooting information by workflow stage to help you quickly find solutions to problems you might face.

Quick Reference

Problem	Quick Solution
Missing packages	Run AWS CodeArtifact login command
API key errors	Check .env file for correct formatting
No modules created	Verify wireframes are in input/wireframes/
Poor quality output	Try a different LLM provider or use Replicate mode
Slow performance	Reduce batch size in configuration

Installation & Setup

"Package not found" or "Unauthorized" errors

When trying to install HAI RapidUI, you might encounter errors about missing packages or unauthorized access. This typically happens because the package is hosted in a private AWS CodeArtifact repository.

Solution: Configure AWS CodeArtifact access with the following command:

aws codeartifact login --tool npm --repository hai-framework --domain hai-framework --domain-owner 442897025632 --region us-east-1 --namespace "@hai"

Make sure you have the correct AWS profile with appropriate permissions, check for typos in AWS commands, and verify your network connectivity.

Environment Configuration

API key authentication failures

If you're seeing error messages about invalid API keys or authentication failures, your API keys might be incorrectly configured.

Solution:

1. Verify your API key format and ensure there are no extra spaces or characters
2. Check your account billing status with the provider
3. Ensure proper permissions are set for the API key
4. Test with a simple request to confirm key validity

Missing environment variables

Error messages about missing API keys or configuration typically indicate issues with your .env file.

Solution:

1. Ensure the .env file exists in your project root directory
2. Verify all required API keys are configured
3. Check for typos in environment variable names
4. Make sure the .env file is properly formatted

Project Structure & Organization

File organization problems

If you're seeing error messages about missing files or directories, your project structure might not be set up correctly.

Solution:

1. Validate that required files exist in the correct locations
2. Check file permissions
3. Verify image formats (PNG/JPG) for wireframes
4. Ensure proper JSON syntax in configuration files

Module creation failures

If you're experiencing errors during module creation or no modules are being created, there might be issues with your wireframes or their organization.

Solution:

1. Ensure wireframes are high-quality and clearly labeled
2. Check that wireframes are in the correct directory (input/wireframes/)
3. Verify wireframe file formats (PNG/JPG)
4. Try processing fewer wireframes at once

Code Generation & Quality

Poor quality output

If the generated code doesn't match your wireframes or has quality issues, you might need to adjust your approach.

Solution:

1. Try different LLM providers to see which works best for your specific wireframes
2. Use higher-quality wireframes with clearer UI elements
3. Add more detailed custom instructions to guide the AI
4. Use the Replicate mode for more precise matching of existing designs

Error Handling & Recovery

Understanding the Error System

HAI RapidUI includes a robust error handling system that automatically detects and attempts to resolve issues. The system monitors for syntax errors, runtime errors, API integration issues, and resource limitations.

When errors are detected:

1. The system automatically retries failed operations
2. Different approaches are used for each retry attempt
3. The number of retries is configurable via ERROR_RETRY_ATTEMPTS (default: 3)
4. Error escalation occurs after ERROR_ESCALATION_THRESHOLD failures (default: 2)

Recovering from Interrupted Sessions

If your session is interrupted:

1. The system preserves state in .hai-rapidui/module_state.json
2. When you restart, it will resume from the last completed batch
3. Conversation history is maintained for context continuity

Dealing with Corrupted Projects

If your project becomes corrupted:

1. Check the error logs for specific issues
2. Try reinitializing with npx @hai/rapidui init
3. If necessary, start with a clean directory and copy over your wireframes

Diagnostic Tools

Log Files

HAI RapidUI maintains comprehensive logs to help diagnose issues:

.hai-rapidui/execution.log      # General execution logs
.hai-rapidui/error.log          # Detailed error logs

State Files

The system also maintains state files that can be useful for troubleshooting:

.hai-rapidui/module_state.json         # Module processing state tracking
.hai-rapidui/conversationhistory.json  # Conversation history management
.hai-rapidui/rapidui.config.json       # Project configuration
.hai-rapidui/errorhandler.json         # Error tracking and retry status

Command-Line Help

For quick reference and troubleshooting:

# Show help information
npx @hai/rapidui --help

# Show version information
npx @hai/rapidui --version

Still Need Help?

If you're still experiencing issues:

• Check the Features documentation for detailed information
• Review Project Organization for structure requirements
• Examine the log files for specific error messages
• Try with a simpler project to isolate the issue