🏠Homix/Documentation
Open App

Troubleshooting Guide

Common issues and solutions for Homix installation and operation.

Installation Issues

Docker not found

Error: command not found: docker

Solution:

  • Install Docker Desktop: docs.docker.com/get-docker
  • On Linux: sudo apt install docker.io (Ubuntu/Debian)
  • Ensure Docker is running: docker version

Permission denied

Error: permission denied while trying to connect to the Docker daemon

Solution:

sudo usermod -aG docker $USER
newgrp docker # or log out and back in

Port already in use

Error: port 8080 already in use

Solution:

  1. Stop the conflicting service: sudo lsof -i :8080
  2. Or edit ~/.homix/docker-compose.yml to use different ports
  3. Change 8080:8080 to 8081:8080
  4. Restart: docker compose up -d

Container failed to start

Error: container homix-edge exited with code 1

Solution:

# Check logs for detailed error
cd ~/.homix && docker compose logs -f

Connectivity Issues

Cannot connect to cloud dashboard

Symptoms: Cloud dashboard shows "connecting..." forever

Solutions:

  1. Check Synadia credentials are in ~/.synadia/
  2. Verify credentials file format (should contain JWT and seed)
  3. Check edge server logs: docker compose logs
  4. Test NATS connectivity: nats server check (if nats CLI installed)

Local dashboard not accessible

Symptoms: http://localhost:8080 times out

Solutions:

  1. Check if container is running: docker ps | grep homix
  2. Verify port mapping: should show 0.0.0.0:8080->8080/tcp
  3. Check firewall settings (Windows/macOS)
  4. Try http://127.0.0.1:8080 instead

Edge server not announcing

Symptoms: No homes appear in cloud dashboard

Solutions:

  1. Check edge server logs for NATS connection errors
  2. Verify internet connectivity from edge server
  3. Check system time is synchronized (important for JWT)
  4. Restart edge server: docker compose restart

Device Issues

Devices not discovered

Symptoms: No devices appear in device list

Solutions:

  1. Ensure devices are on same network as edge server
  2. Check device-specific setup requirements
  3. Verify mDNS/Bonjour is working: avahi-browse -a (Linux)
  4. Manual device addition if auto-discovery fails

Device commands not working

Symptoms: Clicking device controls has no effect

Solutions:

  1. Check device state in edge server logs
  2. Verify device protocol configuration
  3. Test device with manufacturer app first
  4. Check network connectivity to device

Device states not updating

Symptoms: Dashboard shows stale device states

Solutions:

  1. Check NATS subscription in browser console
  2. Verify edge server is publishing state updates
  3. Check for WebSocket connectivity issues
  4. Refresh browser or reconnect to cloud

Performance Issues

High CPU usage

Symptoms: Edge server consuming excessive CPU

Solutions:

  1. Check for automation loops in logs
  2. Reduce device polling frequency
  3. Review automation trigger conditions
  4. Consider hardware upgrade if managing many devices

High memory usage

Symptoms: Edge server using lots of RAM

Solutions:

  1. Check for memory leaks in logs
  2. Reduce device state cache TTL
  3. Restart edge server periodically
  4. Monitor with: docker stats homix-edge

Slow response times

Symptoms: Commands take several seconds to execute

Solutions:

  1. Check network latency to devices
  2. Verify NATS connection health
  3. Use local automation for time-critical operations
  4. Consider edge server hardware upgrade

Debugging Commands

Container Status

# Check if Homix is running
docker ps | grep homix
# View container logs
cd ~/.homix && docker compose logs -f
# Check resource usage
docker stats homix-edge
# Restart services
cd ~/.homix && docker compose restart

Network Debugging

# Check port availability
sudo netstat -tlnp | grep :8080
# Test local dashboard
curl -I http://localhost:8080
# Check DNS resolution
nslookup connect.ngs.global
# Test NATS connectivity (if CLI installed)
nats server ping --server=nats://connect.ngs.global:4222

Configuration Check

# View current configuration
cat ~/.homix/docker-compose.yml
# Check credentials file
ls -la ~/.synadia/
# Validate credentials format
head -5 ~/.synadia/NGS-*.creds

Log Analysis

Common Log Messages

✅ Normal Operation

Connected to NATS via WebSocket
Edge server started successfully
Device discovered: living-room-light

⚠️ Warnings

Failed to connect to device, retrying...
NATS connection lost, reconnecting...
Device state cache expired

❌ Errors

NATS authentication failed
Device protocol error: timeout
Failed to parse automation config

Getting Help

If you're still having issues after trying these solutions:

💬 Community Support

Community Discord coming soon

Discord server setup in progress

🐛 Bug Reports

Report issues on GitHub:

GitHub Issues

When Reporting Issues

Please include the following information:

  • Operating System: Linux distribution, macOS version, etc.
  • Container Platform: Docker version or Podman version
  • Homix Version: From docker images | grep homix
  • Error Messages: Exact error text from logs
  • Steps to Reproduce: What actions led to the issue
  • Configuration: Sanitized version of your setup

Log Collection Script

Use this command to collect system information for bug reports:

cd ~/.homix && docker compose logs --tail=100 > homix-logs.txt

Related Documentation

  • Installation Guide - Complete setup instructions
  • Architecture - Understanding how components work
  • Synadia Setup Guide - Cloud connectivity configuration (coming soon)