# Troubleshooting Guide

Common issues and their solutions.

## Installation Issues

### Node Version Mismatch

**Problem**: `Error: The engine "node" is incompatible with this module`

**Solution**: Use Node.js 18+:
```bash
nvm install 20
nvm use 20
```

### pnpm Not Found

**Problem**: `command not found: pnpm`

**Solution**: Install pnpm:
```bash
npm install -g pnpm
```

## Development Issues

### Port Already in Use

**Problem**: `Error: Port 3000 is already in use`

**Solution**: 
- Kill the process using the port: `lsof -ti:3000 | xargs kill`
- Or use a different port: `PORT=3001 pnpm dev`

### Database Connection Errors

**Problem**: `Error: connect ECONNREFUSED`

**Solution**:
- Ensure PostgreSQL is running: `pg_isready`
- Check connection string in `.env.local`
- Verify database exists: `psql -l`

### Module Not Found Errors

**Problem**: `Module not found: Can't resolve '@/components/...'`

**Solution**:
- Clear `.next` directory: `rm -rf .next`
- Reinstall dependencies: `pnpm install`
- Restart dev server

## Build Issues

### TypeScript Errors

**Problem**: Type errors during build

**Solution**:
- Run type check: `pnpm type-check`
- Fix type errors
- Ensure all dependencies are installed

### Build Fails with Memory Error

**Problem**: `JavaScript heap out of memory`

**Solution**:
```bash
NODE_OPTIONS="--max-old-space-size=4096" pnpm build
```

## Test Issues

### Tests Fail with "Cannot find module"

**Problem**: Tests can't find modules

**Solution**:
- Clear test cache: `pnpm test --clearCache`
- Reinstall dependencies
- Check `vitest.config.ts` paths

### Coverage Not Generated

**Problem**: Coverage report is empty

**Solution**:
- Ensure coverage provider is installed
- Run: `pnpm test:coverage`
- Check `vitest.config.ts` coverage settings

## API Issues

### GraphQL Schema Errors

**Problem**: Schema validation errors

**Solution**:
- Check `api/src/schema/typeDefs.ts`
- Ensure all types are defined
- Verify resolver return types match schema

### Authentication Errors

**Problem**: `UNAUTHENTICATED` errors

**Solution**:
- Check JWT token in request headers
- Verify token hasn't expired
- Ensure `JWT_SECRET` is set in `.env.local`

## Portal Issues

### Keycloak Connection Errors

**Problem**: Cannot connect to Keycloak

**Solution**:
- Verify Keycloak URL in `.env.local`
- Check network connectivity
- Ensure Keycloak is running

### Crossplane API Errors

**Problem**: Cannot reach Crossplane API

**Solution**:
- Verify `NEXT_PUBLIC_CROSSPLANE_API` is set
- Check if running in Kubernetes context
- Verify API endpoint is accessible

## GitOps Issues

### ArgoCD Sync Failures

**Problem**: ArgoCD applications fail to sync

**Solution**:
- Check ArgoCD logs: `kubectl logs -n argocd deployment/argocd-application-controller`
- Verify Git repository access
- Check application manifests

## Performance Issues

### Slow Build Times

**Solution**:
- Use pnpm instead of npm
- Enable build cache
- Reduce bundle size

### Slow Development Server

**Solution**:
- Clear `.next` directory
- Restart dev server
- Check for large files in `public/`

## Getting Help

If you're still experiencing issues:

1. Check existing GitHub issues
2. Search documentation
3. Ask in discussions
4. Open a new issue with:
   - Error message
   - Steps to reproduce
   - Environment details
   - Relevant logs