Troubleshooting Guide¶

This guide helps you resolve common issues you might encounter while working with AIDDDMAP.

Installation Issues¶

Node.js Errors¶

Error: Node.js version not compatible

Solution: Update Node.js to v14 or higher:

nvm install 14
nvm use 14

Docker Issues¶

Error: Cannot connect to the Docker daemon

Solution:

1. Check if Docker is running:

sudo systemctl status docker

1. Start Docker if needed:

sudo systemctl start docker

Environment Variables¶

Error: Missing required environment variable

Solution:

1. Check if .env.local exists
2. Copy from example if needed:

cp .env.example .env.local

1. Fill in all required variables

Runtime Issues¶

AI Agent Connection¶

Error: Cannot connect to AI agent service

Solution:

1. Verify API keys in .env.local
2. Check agent service status
3. Ensure network connectivity

Database Connection¶

Error: Cannot connect to database

Solution:

1. Verify database credentials
2. Check database service status
3. Test connection:

nc -zv localhost 5432

Memory Issues¶

Error: JavaScript heap out of memory

Solution:

1. Increase Node.js memory limit:

export NODE_OPTIONS="--max-old-space-size=4096"

1. Optimize large operations
2. Consider data pagination

Development Issues¶

Build Errors¶

Error: Build failed

Solution:

1. Clear build cache:

npm run clean

1. Remove node_modules:

rm -rf node_modules
npm install

Type Errors¶

Error: Type ... is not assignable to type ...

Solution:

1. Check type definitions
2. Update TypeScript dependencies
3. Run type check:

npm run type-check

Security Issues¶

Encryption Errors¶

Error: Encryption failed

Solution:

1. Verify encryption keys
2. Check encryption mode settings
3. Validate input data format

Authentication Issues¶

Error: Authentication failed

Solution:

1. Clear browser cache
2. Check token expiration
3. Verify credentials

Performance Issues¶

Slow Response Times¶

Solution:

1. Enable performance monitoring
2. Check database query optimization
3. Verify network latency
4. Consider caching strategies

High CPU Usage¶

Solution:

1. Profile application:

node --prof app.js

1. Identify bottlenecks
2. Optimize resource-intensive operations

Common Error Messages¶

"ECONNREFUSED"¶

Cause: Service not running or wrong port Solution:

1. Check service status
2. Verify port configuration
3. Test connectivity

"ENOENT"¶

Cause: File or directory not found Solution:

1. Verify file paths
2. Check file permissions
3. Create missing directories

Getting Help¶

If you're still experiencing issues:

1. Check our GitHub Issues
2. Join our Discord Community
3. Contact support at support@aidddmap.com

Contributing to Troubleshooting¶

Help improve this guide:

1. Submit PRs with new solutions
2. Report undocumented issues
3. Share your troubleshooting experiences