Troubleshooting Guide

General Issues

Services Not Running

Problem: Can't connect to IDE, Jenkins, Gitea, or MailHog

Solutions:

1. Check if services are running:

   docker ps

   Should show containers for code-server, jenkins, gitea, mailhog

2. Restart services:

   docker-compose restart

3. Check logs:

   docker-compose logs -f [service_name]

   Replace [service_name] with: code-server, jenkins, gitea, or mailhog

4. If still down, full restart:

   docker-compose down
   docker-compose up -d

Can't Access IDE

Problem: Browser won't connect to code-server

Solutions:

1. Verify service is running:

   docker ps | grep code-server

2. Check that port 8080 is open:

   curl http://localhost:8080

   Should return HTML (even if errors)

3. Check firewall/security group allows 8080

4. Restart code-server:

   docker-compose restart code-server

Permission Denied on Files

Problem: Can't read/write exercises directory

Solutions:

1. Check permissions:

   ls -la /opt/exercises/

2. Fix if needed:

   sudo chown -R $USER:$USER /opt/exercises/
   chmod -R 755 /opt/exercises/

3. In IDE, try opening a new terminal (sometimes helps)

Exercise-Specific Issues

Python Issues

ImportError / Module Not Found

Problem: ModuleNotFoundError: No module named 'xyz'

Solution:

1. Activate virtual environment:

   source venv/bin/activate  # Linux/Mac
   venv\Scripts\activate      # Windows

2. Install dependencies:

   pip install -r requirements.txt

3. Verify installation:

   python -c "import xyz; print(xyz.__version__)"

Virtual Environment Issues

Problem: Python packages not found even after pip install

Solution:

1. Delete and recreate venv:

   rm -rf venv
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

Node.js / TypeScript Issues

npm Command Not Found

Problem: npm: command not found

Solution:

1. Verify Node.js is installed:

   node --version  # Should be 18+
   npm --version   # Should be 8+

2. If not installed, see Environment Setup

Dependencies Not Installing

Problem: npm install fails or hangs

Solution:

1. Clear cache:

   npm cache clean --force

2. Delete lock files:

   rm -f package-lock.json

3. Try again:

   npm install

TypeScript Compilation Errors

Problem: error TS2307: Cannot find module

Solution:

1. Rebuild:

   npm run clean
   npm install
   npm run build

2. Check that all imports match actual file paths

LLM / API Issues

API Key Errors

Problem: 401 Unauthorized or Invalid API key

Solution:

1. Verify API key is set in .env:

   cat .env | grep -i api_key

2. Check it's in the right format (no quotes, proper prefix)

3. Test API connectivity:

   curl -H "Authorization: Bearer YOUR_KEY" https://api-endpoint.com

Rate Limiting

Problem: rate_limit_exceeded or 429 Too Many Requests

Solution:

1. Wait a few minutes before retrying
2. Add delays between API calls
3. Check if you're within free tier limits
4. See API documentation for rate limits

Timeouts

Problem: API calls timeout or take forever

Solutions:

1. Check network connection
2. Verify API service is up
3. Try a simpler request first
4. Increase timeout values if possible

Git / Repository Issues

Git Config Missing

Problem: fatal: not a git repository

Solution:

1. Initialize git:

   git init
   git add .
   git commit -m "Initial commit"

SSH Key Issues

Problem: Permission denied (publickey)

Solution:

1. Generate SSH key:

   ssh-keygen -t ed25519 -C "your@email.com"

2. Add public key to Gitea (in web interface)

3. Test connection:

   ssh -T git@localhost

Merge Conflicts

Problem: CONFLICT (content merge)

Solution:

1. Check conflicted files:

   git status

2. Edit files, remove conflict markers (<<<<<<<, =======, >>>>>>>)

3. Mark as resolved:

   git add [file]
   git commit -m "Resolve merge conflict"

Testing Issues

Tests Not Running

Problem: pytest or npm test command fails

Solution:

1. Verify test files exist:

   ls test_*.py      # Python
   ls test/**/*.spec.ts  # TypeScript

2. Run with verbose output:

   pytest -v        # Python
   npm test -- --verbose  # TypeScript

3. Check test syntax for errors

Tests Failing

Problem: Tests pass locally but fail in IDE or CI

Debugging Steps:

1. Run single test:

   pytest test_file.py::test_name -v  # Python
   npm test -- --testNamePattern="test_name"  # TypeScript

2. Check test output for specific failure

3. Add debug prints/logging

4. Verify test data is correct

5. Check for environment variable issues

Getting Help

Check Documentation

1. See Learning Path for exercise progression
2. Review Environment Setup for services
3. Check exercise-specific README in the exercises directory

Debug Systematically

1. Read error message carefully
2. Check exact line and code context
3. Look at test output
4. Trace backward from error
5. Check logs: docker-compose logs

Try Common Fixes

• Restart services: docker-compose restart
• Clear caches: rm -rf .cache node_modules
• Reinstall dependencies: pip install -r requirements.txt && npm install
• Rebuild: npm run build or python setup.py build

Ask for Help

1. Check if issue is on Known Issues page
2. Ask instructor or TA
3. Share:
   • Error message (full text)
   • Steps to reproduce
   • What you tried already
   • Current output/logs

Performance Issues

Slow Builds

Problem: npm run build or pytest takes forever

Solutions:

1. Clean build:

   npm run clean && npm run build
   pytest --cache-clear

2. Run in parallel:

   npm run build -- --parallel
   pytest -n auto

3. Check disk space:

   df -h

High Memory Usage

Problem: System becomes slow, containers keep restarting

Solutions:

1. Check memory:

   docker stats

2. Reduce resource limits or restart containers:

   docker-compose restart

3. Clear caches:

   docker system prune
   npm cache clean --force

Still Stuck?

Collect Debug Information

# System info
uname -a
docker --version
python --version
node --version

# Service status
docker ps
docker-compose logs --tail=50

# Your code
git status
git log --oneline -10
cat .env | head

Next Steps

1. Document the issue (exact error, steps to reproduce)
2. Share debug info with instructor
3. Review Architecture for system design
4. Explore Contributing guide for community help

Good luck! You've got this. 🚀