Skip to main content

Troubleshooting

Quick reference for diagnosing and fixing common issues with the Iotistica Agent.

Check agent status​

systemctl status iotistica-agent
journalctl -u iotistica-agent -f

Ping the local API to confirm the agent process is up and listening:

curl -s http://localhost:48484/ping

First-run setup not completing​

On a fresh .deb install, Node.js, Docker, and Mosquitto are installed in the background by iotistica-setup.service. The agent only starts after setup finishes (~1–3 min).

# Watch setup progress live
journalctl -u iotistica-setup -f

# Check whether setup has finished
ls /var/lib/iotistic/setup-complete

If setup-complete exists, setup is done. If the agent still isn't running, check its own logs:

journalctl -u iotistica-agent -n 50 --no-pager

Port 1883 conflict (Mosquitto)​

Symptom: Mosquitto fails to start — Address already in use on port 1883. Common cause: a Docker container already bound to that port.

Check what's occupying port 1883:

sudo ss -tlnp | grep 1883

Fix — switch Mosquitto to a different port (e.g. 8883):

# 1. Change the Mosquitto listener port
sudo nano /etc/mosquitto/conf.d/iotistica.conf
# Change:  listener 1883
# To:      listener 8883

# 2. Update the agent to match
sudo nano /etc/iotistic/agent.env
# Change:  MQTT_BROKER_URL=mqtt://localhost:1883
# To:      MQTT_BROKER_URL=mqtt://localhost:8883

# 3. Restart both services
sudo systemctl restart mosquitto
sudo systemctl restart iotistica-agent

:::tip Set the port at install time If you haven't installed yet, pass MQTT_BROKER_PORT to avoid the conflict entirely:

sudo MQTT_BROKER_PORT=8883 dpkg -i iotistica-agent_*.deb

:::

Admin UI not reachable from the network​

Symptom: Browser can't connect to http://<device-ip>:48484/admin/.

Check which address the agent is actually listening on:

sudo ss -tlnp | grep node

If it shows 127.0.0.1:48484 instead of 0.0.0.0:48484, the security mode is set to LOCALHOST_ONLY. Fix:

sudo nano /etc/iotistic/agent.env
# Set:  API_SECURITY_MODE=LOCAL_NETWORK

sudo systemctl restart iotistica-agent

Valid values for API_SECURITY_MODE: LOCALHOST_ONLY, LOCAL_NETWORK, API_KEY, OPEN.

Agent fails to start — module not found​

Symptom: journalctl -u iotistica-agent shows Cannot find module '...'.

Reinstalling the package is the cleanest fix:

sudo apt install ./iotistica-agent_*.deb

As a quick workaround if packages are present in the agent directory but node_modules is missing:

sudo ln -s . /opt/iotistic/agent/node_modules
sudo systemctl restart iotistica-agent

_apt permission warning during install​

Symptom:

N: Download is performed unsandboxed as root as file '/home/user/iotistica-agent_*.deb'
   couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

This is a harmless note (N:) — not an error. apt can't sandbox the file read because /home/user/ is not accessible to the _apt user. The installation still completes successfully.

To avoid it, either copy to /tmp first or use dpkg -i directly:

sudo dpkg -i ~/iotistica-agent_*.deb

Reinstall / upgrade​

Reinstalling over an existing installation preserves agent.env and agent data. The first-run setup does not re-run (guarded by the setup-complete flag).

sudo apt install ./iotistica-agent_<version>_arm64.deb
# or
sudo dpkg -i iotistica-agent_<version>_arm64.deb

Useful log commands​

# Agent logs (last 50 lines)
journalctl -u iotistica-agent -n 50 --no-pager

# First-run setup logs
journalctl -u iotistica-setup --no-pager

# Mosquitto logs
journalctl -u mosquitto -n 50 --no-pager

# All Iotistica services at once
journalctl -u 'iotistica-*' -f