Skip to main content

Troubleshooting

Common issues and their solutions when working with RegistryAccord.

Common Pitfalls​

Port Conflicts​

Issue: Services fail to start due to port conflicts.

Solution: Check if ports 3000-3002 are already in use:

# Check for processes using RegistryAccord ports
lsof -i :3000
lsof -i :3001
lsof -i :3002

# Kill conflicting processes if needed
kill -9 <PID>

Alternatively, modify the docker-compose.yml to use different ports.

Docker Memory Issues​

Issue: Services crash or become unresponsive due to insufficient memory.

Solution: Increase Docker memory allocation:

  1. Open Docker Desktop preferences
  2. Go to Resources > Memory
  3. Increase allocation to at least 4GB
  4. Restart Docker

Slow Image Pulls​

Issue: Docker images take a long time to download.

Solution:

  • Ensure stable internet connection
  • Use a Docker registry mirror if available
  • Pre-pull images during off-peak hours

JWKS Cache TTL​

Issue: Authentication failures due to stale JWKS cache.

Solution:

  • Wait for natural cache expiration (typically 5 minutes)
  • Restart services to force cache refresh
  • Check Identity service health endpoint

Compose Health Retries​

Issue: Services show as unhealthy in Docker Compose.

Solution:

# Check service logs
docker-compose logs identity

# Force recreate containers
docker-compose up --force-recreate

# Check individual service health
curl http://localhost:3000/health

Development Issues​

Environment Variables​

Issue: Services not picking up configuration.

Solution:

  • Check .env file is properly formatted
  • Ensure variables are exported in shell
  • Restart services after configuration changes

Database Connection​

Issue: Services can't connect to PostgreSQL.

Solution:

  • Verify PostgreSQL is running
  • Check connection string in configuration
  • Ensure proper network access between containers

CLI and SDK Issues​

Authentication Failures​

Issue: JWT validation errors.

Solution:

  • Verify Identity service is running
  • Check JWKS endpoint: curl http://localhost:3000/.well-known/jwks.json
  • Ensure proper audience and issuer configuration
  • Regenerate session tokens

Network Errors​

Issue: Connection timeouts or refused connections.

Solution:

  • Verify all services are running
  • Check firewall settings
  • Ensure proper port mapping in Docker
  • Test connectivity: curl http://localhost:3000/health

Debugging Tips​

  1. Enable verbose logging by setting appropriate environment variables
  2. Check service health endpoints regularly
  3. Monitor container logs with docker-compose logs -f
  4. Use the devstack make targets for common operations

If issues persist, please check our GitHub Issues or reach out to the community for support.