Troubleshoot Pairing

Solutions for common pairing problems between OctoMY™ nodes.

Pro Tip

Most pairing problems are caused by firewalls blocking UDP ports 8124/8125. Check your firewall first - it's the most common issue and the easiest to fix.

Quick diagnosis

Agent not found

Symptom

Remote shows "No agents found" even though Agent is running.

Causes and solutions

1. Discovery not enabled on Agent

Check Agent settings:

Agent → ☰ Menu → Settings → Auto Discovery [✓]

2. Different networks

Verify both devices on same network:

# On Agent device
ip addr show | grep "inet "
# Look for: inet 192.168.1.xxx

# On Remote device
ip addr show | grep "inet "
# Should show same network prefix: 192.168.1.xxx

3. Firewall blocking UDP

Open required ports:

# Linux
sudo ufw allow 8124/udp
sudo ufw allow 8125/udp

# Check status
sudo ufw status

4. Network blocks broadcast

Some enterprise/hotel networks block UDP broadcast. Solutions:

• Use QR pairing instead
• Connect to a different network
• Use manual connection with IP address

5. Discovery hasn't completed

Discovery can take 10-30 seconds. Wait and try:

Remote → ☰ Menu → Settings → Refresh Discovery

Pairing rejected

Symptom

Remote initiates pairing but Agent rejects it.

Causes and solutions

1. Wrong Agent selected

Verify identicons match:

• Compare the icon shown on Remote
• With the icon the Agent shows about itself
• They must be identical

2. Auto-reject enabled

The Agent may have strict pairing settings:

Agent → ☰ Menu → Settings → Pairing
  [ ] Auto Accept (should be checked for testing)

3. Agent busy

If Agent is already handling another pairing:

• Wait for current pairing to complete
• Try again

4. Incompatible versions

Check both devices run compatible versions:

./agent --version
./remote --version

Connection timeout

Symptom

Pairing starts but times out before completing.

Causes and solutions

1. Network latency too high

Check connectivity:

ping <agent-ip>
# Should be < 100ms for reliable pairing

2. Firewall blocking handshake

The pairing handshake requires bidirectional UDP:

# On Agent device
nc -u -l 8124 &
echo "test" | nc -u <remote-ip> 8125

# On Remote device
nc -u -l 8125 &
echo "test" | nc -u <agent-ip> 8124

3. NAT issues

If devices are behind different NATs:

• Enable Zoo connection for NAT traversal
• Use QR pairing with direct IP

4. Timeout too short

Increase pairing timeout:

Settings → Connection → Pairing Timeout → 30 seconds

Wrong trust level

Symptom

Pairing succeeded but Remote can't control Agent.

Causes and solutions

1. Trust level too low

Check current trust level:

Agent → ☰ Menu → Pairing → [Select Remote]

Required levels for actions:

2. Raise trust level

Agent → ☰ Menu → Pairing → [Select Remote] → Trust Level
  Select: Trust (4)
  [Save]

Trust relationship lost

Symptom

Previously paired devices no longer recognize each other.

Causes and solutions

1. Address book deleted/corrupted

Check address book exists:

ls ~/.local/share/OctoMY™/OctoMY\ Agent/<personality>/addressbook.json

If missing, you need to re-pair.

2. Key regenerated

If the Agent's identity was reset:

• The old trust relationship is invalid
• Must pair again with the new identity

3. Different personality

Check both devices using same personality:

# Compare what's shown in the title bar
# Agent: "OctoMY Agent - MyRobot"
# Remote should connect to "MyRobot", not a different personality

Diagnostic commands

Check node status

# Is the Agent running?
ps aux | grep agent

# What port is it using?
ss -ulnp | grep 8124

# Check log for errors
journalctl -u octomy-agent --since "10 minutes ago"

Test network connectivity

# Ping test
ping <other-device-ip>

# UDP port test
nc -zvu <other-device-ip> 8124

# Check route
traceroute <other-device-ip>

Check discovery broadcast

# Listen for discovery broadcasts
tcpdump -i any udp port 8124

# Should see periodic packets when discovery is active

Reset and start fresh

If all else fails, reset the pairing:

On agent

# Remove specific peer from address book
Agent → ☰ Menu → Pairing → [Select Remote] → [Remove]

# Or reset entire address book (removes all peers)
rm ~/.local/share/OctoMY™/OctoMY\ Agent/<personality>/addressbook.json

On remote

# Remove specific Agent
Remote → ☰ Menu → Pairing → [Select Agent] → [Forget]

# Or reset entire address book
rm ~/.local/share/OctoMY™/OctoMY\ Remote/<personality>/addressbook.json

Then pair again from scratch.

Common error messages

Getting more help

Enable debug logging

./agent --debug --personality MyRobot 2>&1 | tee agent-debug.log

Check logs

# View recent logs
tail -f ~/.local/share/OctoMY™/OctoMY\ Agent/<personality>/logs/current.log

Report issues

If problems persist:

1. Collect debug logs from both devices
2. Note the exact error messages
3. Report at https://github.com/mrdeveloperdude/OctoMY/issues