6f28146ac3
- Complete project structure with Next.js frontend - GraphQL API backend with Apollo Server - Portal application with NextAuth - Crossplane Proxmox provider - GitOps configurations - CI/CD pipelines - Testing infrastructure (Vitest, Jest, Go tests) - Error handling and monitoring - Security hardening - UI component library - Documentation
174 lines
3.3 KiB
Markdown
174 lines
3.3 KiB
Markdown
# 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
|
|
|