Sankofa/docs/TROUBLESHOOTING.md

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+:

nvm install 20
nvm use 20

pnpm Not Found

Problem: command not found: pnpm

Solution: Install pnpm:

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:

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