Troubleshooting

OPS Intermediate

Common issues and solutions for EZ-Console deployments.

Overview

This guide helps you resolve common issues when deploying and operating EZ-Console applications. For development issues, see the Troubleshooting Guide.

Server Issues

Server Won't Start

Symptom: Server fails to start or exits immediately

Common Causes:

1. Port already in use

# Check if port is in use
lsof -i :8080
netstat -tulpn | grep 8080

# Solution: Use different port
./server --server.port=9090

2. Invalid encryption key

# Error: encryption key must be 8, 16, 24, or 32 bytes
# Solution: Use correct length
./server --global.encrypt-key=12345678  # 8 bytes
./server --global.encrypt-key=1234567890123456  # 16 bytes

3. Database connection failed

# Check database connectivity
mysql -h localhost -u root -p
psql -h localhost -U postgres

# Verify connection settings in config.yml
database:
  driver: "mysql"
  host: "localhost"
  username: "root"
  password: "correct-password"

4. Missing configuration file

# Ensure config file exists
ls -l config.yml

# Or specify full path
./server --config=/etc/myapp/config.yml

Server Crashes Randomly

Symptom: Server stops unexpectedly

Solutions:

1. Check logs for panic messages:

journalctl -u myapp -n 100
tail -f /var/log/myapp.log

2. Check system resources:

# Memory usage
free -h

# CPU usage
top
htop

# Disk space
df -h

3. Enable debug mode:

./server --server.mode=debug --log.level=debug

Database Issues

Connection Timeout

Symptom: Database queries timeout

Solutions:

1. Increase timeout:

database:
  read_timeout: "30s"
  max_connection_life_time: "5m"

2. Check network:

ping db-host
telnet db-host 3306

3. Increase connection pool:

database:
  max_open_connections: 200
  max_idle_connections: 20

Slow Queries

Symptom: API responses are slow

Solutions:

1. Enable slow query logging:

database:
  slow_threshold: "1s"

2. Add database indexes:

type Product struct {
    Name     string `gorm:"size:100;index"`
    Category string `gorm:"size:50;index"`
}

3. Use preloading:

// Bad: N+1 queries
products, _ := db.Find(&products)
for _, p := range products {
    category, _ := db.Find(&category, p.CategoryID)
}

// Good: Single query
db.Preload("Category").Find(&products)

Migration Errors

Symptom: Database migration fails

Solutions:

1. Check database permissions:

GRANT ALL PRIVILEGES ON database.* TO 'user'@'%';
FLUSH PRIVILEGES;

2. Manually run migration:

# Backup first
mysqldump database > backup.sql

# Check logs
tail -f /var/log/myapp.log

Authentication Issues

Token Expired

Symptom: "E4011: Token expired" error

Solutions:

1. Re-authenticate: User needs to log in again
2. Extend token lifetime:

jwt:
  expiration: "24h"  # Increase from default

Session Expired

Symptom: "E4011: Session expired, please login again"

Solutions:

1. Adjust session settings through UI:

   • System Settings → Security Settings
   • Increase "Session Idle Timeout"

2. Or via configuration:

# Through system settings
session_idle_timeout_minutes: "120"

Permission Denied

Symptom: "E4031: No permission to perform this operation"

Solutions:

1. Check user roles:

   • User Management → User Detail → Roles tab
   • Verify roles are assigned

2. Check permission assignment:

   • Role Management → Role Detail → Permissions tab
   • Verify permissions are assigned

3. Verify permission code:

   • Ensure permission is registered in code
   • Check permission format: module:resource:action

Frontend Issues

White Screen / Blank Page

Symptom: Frontend shows blank page

Solutions:

1. Check browser console for errors (F12)
2. Verify API endpoint:

// Check vite.config.ts proxy settings
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
    },
  },
}

3. Clear browser cache and rebuild:

rm -rf node_modules/.vite
pnpm build

API Calls Failing

Symptom: API requests return errors

Solutions:

1. Check CORS settings:

   • Verify CORS middleware is enabled
   • Check allowed origins

2. Verify authentication token:

console.log(localStorage.getItem('token'));

3. Check network tab in browser (F12 → Network)

Build Errors

Symptom: Frontend build fails

Solutions:

1. Clear dependencies and reinstall:

rm -rf node_modules pnpm-lock.yaml
pnpm install

2. Check TypeScript errors:

pnpm run type-check

3. Update dependencies:

pnpm update

Performance Issues

High Memory Usage

Solutions:

1. Check for memory leaks:

watch -n 1 'ps aux | grep server'

2. Adjust garbage collection:

GOGC=50 ./server  # More aggressive GC

3. Profile application:

import _ "net/http/pprof"

router.GET("/debug/pprof/*any", gin.WrapH(http.DefaultServeMux))

High CPU Usage

Solutions:

1. Check slow queries:

database:
  slow_threshold: "0s"  # Log all queries

2. Add caching:

cache.Set(key, value, 5*time.Minute)

3. Optimize queries:

// Use Select to limit fields
db.Select("id", "name").Find(&products)

// Use pagination
db.Offset(offset).Limit(limit).Find(&products)

Slow API Responses

Solutions:

1. Add indexes:

type Model struct {
    Field string `gorm:"index"`
}

2. Use eager loading:

db.Preload("Relations").Find(&models)

3. Implement caching:

if cached, ok := cache.Get(key); ok {
    return cached
}

Configuration Issues

Environment Variables Not Working

Solutions:

1. Check variable naming:

# Must be uppercase with underscores
export DATABASE_HOST=localhost  # ✓ Correct
export database-host=localhost  # ✗ Wrong

2. Verify loading:

printenv | grep DATABASE

3. Check precedence:

Command-line args > Environment variables > Config file

Configuration Not Applied

Solutions:

1. Verify config file path:

./server --config=/path/to/config.yml

2. Check YAML syntax:

yamllint config.yml

3. Check logs for parsing errors:

./server --log.level=debug

Docker Issues

Container Won't Start

Solutions:

1. Check container logs:

docker logs container-name

2. Verify environment variables:

docker inspect container-name

3. Check volume mounts:

docker run -v /host/path:/container/path ...

Cannot Connect to Database

Solutions:

1. Use Docker network:

docker network create myapp-network
docker run --network myapp-network ...

2. Use service names:

# docker-compose.yml
database:
  host: "db"  # Use service name, not localhost

Common Error Codes

Code	Meaning	Solution
E4001	Bad Request	Check request parameters
E4011	Unauthorized	Re-authenticate or check token
E4012	Invalid User	User not found or disabled
E4031	Forbidden	Check user permissions
E4041	Not Found	Resource doesn't exist
E5001	Server Error	Check server logs
E5031	Service Unavailable	Check service status

Debug Mode

Enable debug mode for more information:

./server \
  --server.mode=debug \
  --log.level=debug \
  --log.format=logfmt

Getting Help

1. Check Logs:

journalctl -u myapp -n 100 -f
tail -f /var/log/myapp.log

2. Enable Debug Mode:

./server --log.level=debug

3. Review Documentation:

   • Check relevant guide sections
   • Review API documentation at /swagger

4. Search Issues:

   • Check GitHub issues
   • Search similar problems

Related Topics

• Deployment Strategies - Deployment methods
• Database Migration - Migration issues
• FAQ - Common questions

---

Need help? Ask in GitHub Discussions.