DataForeman Troubleshooting Guide

This guide helps you diagnose and fix common DataForeman problems.

Quick Diagnostic Checklist

Run through this checklist first:

1
2
3


# 1. Check if Docker is running
docker --version
# Should show: Docker version 20.x.x or higher

Open a terminal in DataForeman folder and run:

1
2
3
4
5
6


# 2. Check container status
docker compose ps
# All services should show "Up"

# 3. Check for errors in logs
docker compose logs --tail 50

Problem: Can’t Access http://localhost:8080

Symptom

Browser shows “Unable to connect” or “This site can’t be reached”

Solutions

Solution 1: Check if containers are running

Open a terminal in DataForeman folder and type:

1

docker compose ps

Look for services with “Exited” status. If any are exited:

1

docker compose up -d

Solution 2: Check if port 8080 is already in use

1

sudo lsof -i :8080

If another program is using port 8080, either:

Stop that program, or
Edit docker-compose.yml to change the front service port from 8080:80 to 8081:80

Solution 3: Check frontend logs

1

docker compose logs front

Look for error messages in the output.

Solution 4: Restart everything

1
2


docker compose down
docker compose up -d

Wait 30-60 seconds, then try accessing http://localhost:8080 again.

Problem: Permission Denied Errors

Symptom

Containers show errors like:

Permission denied: '/app/logs/core/core.log'
FATAL: could not open log file: Permission denied

Solution

Open a terminal in DataForeman folder and type:

1
2


./fix-permissions.sh
docker compose restart

Why This Happens

The containers run as specific user IDs that need write access to log directories. The fix-permissions script sets the correct permissions.

Make It Permanent

If this happens after every reboot, add the script to your startup:

1
2
3
4
5


# Edit crontab
crontab -e

# Add this line (replace ~/DataForeman with your actual path):
@reboot cd /home/YOUR_USERNAME/DataForeman && ./fix-permissions.sh

Problem: Containers Keep Restarting

Symptom

Running docker compose ps shows containers constantly restarting:

NAME              STATUS
core-1            Restarting (1) 5 seconds ago

Solutions

Solution 1: Check memory usage

1

docker stats --no-stream

If memory usage is near 100%, you need more RAM. DataForeman needs at least 4GB.

Solution 2: Check container logs

1
2
3
4
5


# Check which container is failing
docker compose ps

# View logs for that container (replace 'core' with your failing service)
docker compose logs core --tail 100

Solution 3: Rebuild containers

1
2
3


docker compose down
docker compose build --no-cache
docker compose up -d

Problem: Database Connection Errors

Symptom

Core service logs show:

Error: connect ECONNREFUSED 127.0.0.1:5432
Failed to connect to database

Solutions

Solution 1: Check if database is running

1

docker compose ps db tsdb

Both should show “Up”. If not:

1

docker compose up -d db tsdb

Solution 2: Check database logs

1
2


docker compose logs db
docker compose logs tsdb

Solution 3: Restart in correct order

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Stop everything
docker compose down

# Start databases first
docker compose up -d db tsdb

# Wait 10 seconds
sleep 10

# Start everything else
docker compose up -d

Symptom

Solutions

Solution 1: Use default credentials

Email: admin@example.com
Password: password

Solution 2: Reset admin password

If you’ve forgotten your password, you need to reset it by recreating the admin user.

Open a terminal in DataForeman folder and type:

1
2


# Edit the .env file to set a new password
nano .env

Find ADMIN_PASSWORD= and set a new password. Save (Ctrl+X, Y, Enter).

Then delete and recreate the admin user:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Connect to the database
docker compose exec db psql -U dataforeman dataforeman

# Delete the admin user
DELETE FROM users WHERE email = 'admin@example.com';

# Exit the database
\q

# Restart core to recreate admin with new password from .env
docker compose restart core

Wait 10 seconds, then try logging in with the new password.

Important: The .env password is only used when creating the admin user. Once you change your password in the app, it’s stored in the database and .env is no longer used.

Solution 3: Check if database has admin user

1

docker compose exec db psql -U dataforeman -c "SELECT email FROM users WHERE email='admin@example.com';"

If empty, the admin user wasn’t created. Check core logs:

1

docker compose logs core --tail 100 | grep admin

Problem: Out of Disk Space

Symptom

Errors mentioning “no space left on device”

Solutions

Solution 1: Check disk usage

1
2


df -h
docker system df

Solution 2: Clean up Docker

1
2
3
4
5


# Remove unused Docker images and containers
docker system prune -a

# Remove unused volumes (⚠️ WARNING: This removes ALL unused volumes)
docker system prune --volumes

Solution 3: Configure data retention

Access DataForeman at http://localhost:8080
Go to Diagnostic → Capacity → Retention Policy
Set retention period (e.g., 30 days)
Enable compression
Click Save

Solution 4: Manual database cleanup

1
2
3
4
5
6
7
8


# Connect to TimescaleDB
docker compose exec tsdb psql -U dataforeman dataforeman_ts

# Check table sizes
SELECT pg_size_pretty(pg_total_relation_size('tag_values'));

# Exit
\q

Problem: Slow Performance

Symptom

Web interface is slow, pages take long to load

Solutions

Solution 1: Check system resources

1
2
3
4
5


# Check CPU and memory usage
docker stats --no-stream

# Check host system
top

Solution 2: Check database size

1

docker compose exec tsdb psql -U dataforeman dataforeman_ts -c "SELECT pg_size_pretty(pg_database_size('dataforeman_ts'));"

If very large (>10GB), configure data retention.

Solution 3: Restart services

1

docker compose restart

Solution 4: Check network latency

1
2


# From inside container to database
docker compose exec core ping -c 3 db

Problem: Can’t Connect to Industrial Devices

Symptom

Device shows “disconnected” or “error” in DataForeman

Solutions

Solution 1: Check network connectivity

1
2


# From inside connectivity container
docker compose exec connectivity ping -c 3 <device-ip>

Solution 2: Check firewall

1
2


# Check if outbound connections are allowed
sudo ufw status

Solution 3: Check device configuration

Verify IP address is correct
Verify port is correct (102 for S7, 44818 for EIP, 4840 for OPC UA)
Verify device is powered on and accessible from the DataForeman host

Solution 4: Check connectivity logs

1

docker compose logs connectivity --tail 100

Problem: Windows VM - Discovery Not Working

Symptom

Network discovery doesn’t find devices (but direct IP connection works)

Solution

Your VM network must be in Bridged mode, not NAT

Shut down the VM
Open VM settings
Go to Network settings
Change from “NAT” or “Shared” to “Bridged Adapter”
Start the VM
Restart DataForeman

Why: UDP broadcast packets (used for discovery) cannot traverse NAT. Direct connections work because they use TCP to a specific IP.

Getting More Help

If none of these solutions work:

1. Collect Diagnostic Information

Open a terminal in DataForeman folder and type:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# Check versions
docker --version
docker compose version
git describe --tags

# Check all logs
docker compose logs > /tmp/dataforeman-logs.txt

# Check system resources
docker stats --no-stream --no-trunc > /tmp/dataforeman-stats.txt
df -h > /tmp/dataforeman-disk.txt
free -h > /tmp/dataforeman-memory.txt

2. Create a GitHub Issue

Go to GitHub Issues and create a new issue with:

What you were trying to do
What happened instead
Error messages (from logs)
System information (from diagnostic commands above)
Steps to reproduce the problem

3. Search Existing Issues

Before creating a new issue, search existing issues - your problem might already be solved!

Complete Reset (Last Resort)

⚠️ WARNING: This will delete ALL your data!

Only do this if instructed or if you want to start completely fresh.

Open a terminal in DataForeman folder and type:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Stop and remove everything
docker compose down -v

# Remove all DataForeman containers and images
docker compose rm -f
docker rmi $(docker images | grep dataforeman | awk '{print $3}')

# Start fresh
./fix-permissions.sh
docker compose up -d

Preventive Maintenance

To avoid problems:

Weekly

Check disk space: df -h
Check container status: docker compose ps

Monthly

Review logs for errors: docker compose logs --tail 200
Clean up Docker: docker system prune

After System Updates/Reboots

Open a terminal in DataForeman folder and type:

1
2


./fix-permissions.sh
docker compose up -d

Before Updating DataForeman

Open a terminal in DataForeman folder and type:

1
2
3


# Backup your data (just in case)
docker compose exec db pg_dump -U dataforeman dataforeman > /tmp/backup-$(date +%Y%m%d).sql
docker compose exec tsdb pg_dump -U dataforeman dataforeman_ts > /tmp/backup-ts-$(date +%Y%m%d).sql

Still stuck? Create a GitHub issue with your logs and we’ll help you out.

DataForeman Troubleshooting Guide

Quick Diagnostic Checklist

Problem: Can’t Access http://localhost:8080

Symptom

Solutions

Problem: Permission Denied Errors

Symptom

Solution

Why This Happens

Make It Permanent

Problem: Containers Keep Restarting

Symptom

Solutions

Problem: Database Connection Errors

Symptom

Solutions

Problem: Can’t Login / Invalid Credentials

Symptom

Solutions

Problem: Out of Disk Space

Symptom

Solutions

Problem: Slow Performance

Symptom

Solutions

Problem: Can’t Connect to Industrial Devices

Symptom

Solutions

Problem: Windows VM - Discovery Not Working

Symptom

Solution

Getting More Help

1. Collect Diagnostic Information

2. Create a GitHub Issue

3. Search Existing Issues

Complete Reset (Last Resort)

Preventive Maintenance

Weekly

Monthly

After System Updates/Reboots

Before Updating DataForeman