Troubleshooting

Common issues and solutions for DataMate

This document provides troubleshooting steps and solutions for common DataMate issues.

Service Startup Issues

Service Won’t Start

Symptoms

Service fails to start or exits immediately after running make install.

Troubleshooting Steps

  1. Check Port Conflicts
# Check port usage
lsof -i :8080  # API Gateway
lsof -i :30000 # Frontend

If port is occupied:

# Kill process
kill -9 <PID>
  1. View Container Logs
# View all containers
docker ps -a

# View specific container logs
docker logs datamate-backend
  1. Check Docker Resources
# View Docker system info
docker system df

# Clean unused resources
docker system prune -a

Common Causes and Solutions

CauseSolution
Port occupiedKill process or modify port mapping
Insufficient memoryIncrease Docker memory limit
Image not pulledRun docker pull
Network issuesCheck firewall and network config

Container Exits Immediately

Troubleshooting

# View exit code
docker ps -a

# View detailed logs
docker logs <container-name> --tail 100

Database Connection Issues

Cannot Connect to Database

Troubleshooting Steps

  1. Check Database Container
docker ps | grep datamate-database
docker logs datamate-database
  1. Test Database Connection
# Enter database container
docker exec -it datamate-database psql -U postgres -d datamate
  1. Check Database Config
# Check environment variables
docker exec datamate-backend env | grep DB_

Frontend Issues

Frontend Not Accessible

Symptoms

Browser cannot access http://localhost:30000

Troubleshooting

  1. Check Frontend Container
docker ps | grep datamate-frontend
docker logs datamate-frontend
  1. Check Port Mapping
docker port datamate-frontend

API Request Failed

Troubleshooting

  1. Check Browser Console

Open browser DevTools → Network tab

  1. Check API Gateway
docker ps | grep datamate-gateway
docker logs datamate-gateway
  1. Test API
curl http://localhost:8080/actuator/health

Task Execution Issues

Task Stuck

Troubleshooting

  1. View Task Logs
docker logs datamate-backend --tail 100 | grep <task-id>
docker logs datamate-runtime --tail 100
  1. Check System Resources
docker stats

Performance Issues

Slow System Response

Troubleshooting

  1. Check System Resources
docker stats
  1. Check Database Performance
-- View active queries
SELECT * FROM pg_stat_activity WHERE state = 'active';

Memory Overflow

Troubleshooting

# Check exit reason
docker inspect <container> | grep OOMKilled

Log Viewing

View Application Logs

# Backend logs
docker logs datamate-backend --tail 100 -f

# Frontend logs
docker logs datamate-frontend --tail 100 -f

Log File Locations

ServiceLog Path
Backend/var/log/datamate/backend/app.log
Frontend/var/log/datamate/frontend/
Database/var/log/datamate/database/
Runtime/var/log/datamate/runtime/

Getting Help

If issues persist:

  1. Collect Information

    • Error messages
    • Log files
    • System environment
    • Reproduction steps

  2. Search Existing Issues

Visit GitHub Issues

  1. Submit New Issue

Include:

  • DataMate version
  • OS version
  • Docker version
  • Detailed error messages
  • Reproduction steps

Last modified February 9, 2026: :memo: add english docs (3868c82)