Troubleshooting

This page covers common issues you may encounter with edge deployments and how to resolve them. Commands below use <alias> as a placeholder for your deployment's alias — the gateway's containers are named fleetera-runtime-<alias>, fleetera-edge-crawler-<alias>, and fleetera-watchtower-<alias>, and its install directory is /opt/fleetera-edge/<alias> by default.

Bootstrap and installation

Token expired

Symptom: The installation command fails with an authentication error.

Cause: Bootstrap tokens expire after 24 hours.

Solution:

1. Navigate to the deployment detail page
2. Click Regenerate Token
3. Copy the new installation command
4. Run it on the edge server

Token already used

Symptom: The installation command fails because the token has already been consumed.

Cause: Each bootstrap token can only be used once. A previous installation attempt consumed the token.

Solution: Regenerate the token from the deployment detail page and run the updated command.

Connectivity check fails

Symptom: The bootstrap script exits early with a connectivity error before installing anything.

Cause: The script probes outbound HTTPS (port 443) to the platform API, the container registry, and configuration storage before making any changes. A corporate firewall blocking any of these fails the probe.

Solution: Allow outbound port 443 from the edge server to the endpoints listed in the script's error message, then re-run the command. No inbound ports are required.

Docker installation fails

Symptom: The bootstrap script fails during the Docker installation step.

Cause: The server may not meet the hardware requirements or may be running an unsupported operating system.

Solution:

1. Verify the server runs a supported Linux distribution (Ubuntu 22.04+, Debian 11+, or Raspberry Pi OS 64-bit)
2. Ensure the server has internet access to download Docker packages
3. Check that you are running the command with sudo
4. Try installing Docker manually and then re-running the bootstrap command

VPN connection fails

Symptom: The bootstrap script installs Docker but fails to establish the VPN connection.

Cause: The server cannot reach the VPN coordination servers, or the auth key has expired.

Solution:

1. Verify the server has outbound internet access
2. Check that no firewall is blocking outbound HTTPS traffic
3. Regenerate the token (which also generates a new VPN auth key)
4. Run the updated installation command

Gateway offline

Deployment stays in Pending status

Symptom: After running the bootstrap command, the deployment remains in Pending status.

Cause: The bootstrap script did not complete successfully, or the first heartbeat was not received.

Solution:

1. Check the installation progress steps on the deployment page — the script reports each step, so a failed step is visible there
2. Check the bootstrap script output on the edge server for errors
3. Verify the runtime container is running: docker ps --filter "name=fleetera-runtime-<alias>"
4. Check the runtime logs: docker logs fleetera-runtime-<alias>

Deployment goes Offline

Symptom: The deployment status changes from Online to Offline.

Cause: The cloud has not received a heartbeat from the gateway for five or more minutes. The runtime sends a heartbeat every 60 seconds; missing several in a row usually means:

• Network connectivity loss at the site
• The runtime container stopped or crashed
• Server reboot or shutdown

Solution:

1. Check that the edge server is powered on and connected to the network
2. Verify the runtime container is running: docker ps --filter "name=fleetera-runtime-<alias>"
3. Restart the stack if needed: cd /opt/fleetera-edge/<alias> && docker compose up -d
4. Check the runtime logs for errors: docker logs fleetera-runtime-<alias>
5. Verify the VPN connection is active on the host: tailscale status

No VPN IP displayed

Symptom: The deployment detail page shows "Not connected" for the VPN IP.

Cause: The gateway has not yet sent a heartbeat with its VPN IP, or the VPN client on the host is not running.

Solution:

1. On the edge server, check the VPN client: tailscale status
2. If the runtime is not running, restart the stack: cd /opt/fleetera-edge/<alias> && docker compose up -d

Configuration not applying

Sync status stuck on Pending or Applying

Symptom: You publish a configuration but the sync status does not reach In Sync.

Cause: The runtime polls for configuration every 30 seconds and reports the applied version back. If the gateway is offline or the runtime container is down, the new version is never picked up.

Solution:

1. Verify the deployment is Online
2. Wait up to 30 seconds for the next poll cycle
3. Check the runtime logs to confirm it is polling: docker logs fleetera-runtime-<alias>
4. Restart the runtime container if it appears wedged: docker restart fleetera-runtime-<alias>

See Sync Status and Error Handling for details.

Docker Compose is stale

Symptom: The Docker Compose card on the deployment's Overview page shows Stale — the compose the gateway is running no longer matches what the platform would generate for it (for example, after enabling a utility service or changing buffer settings).

Cause: Container images update automatically via Watchtower, but the compose file itself is only replaced by hand — the platform never reaches into your host.

Solution: Follow the steps on the card:

1. Click Regenerate compose to refresh the stored configuration
2. Download the new docker-compose.yml from the deployment's Configuration page
3. Copy it into the gateway's install directory (/opt/fleetera-edge/<alias> by default) on the host, then re-apply it:

cd /opt/fleetera-edge/<alias>
docker compose up -d

The card compares the running compose hash against the expected one, so it flips back to Current on the next heartbeat after you re-apply.

Data not flowing

Symptom: The gateway is online and configuration is In Sync, but no telemetry data appears in the platform.

Cause: A protocol driver cannot connect to the industrial data source, the binding configuration is incorrect, or data is stuck in the store-and-forward buffer.

Solution:

1. Open the deployment's Monitoring page and check the per-connector driver status — each driver reports connected/disconnected/error with its last error message
2. Check the Edge Buffer Health card on the same page — if the buffer is filling and the drain rate is zero, the gateway is collecting data but cannot reach the cloud data pipeline; check site connectivity
3. Verify the connector endpoint is reachable from the edge server
4. Review the binding configuration for correct addresses
5. Check the runtime logs for driver errors: docker logs fleetera-runtime-<alias>

Automatic updates not happening

Symptom: The gateway keeps running old container versions after a platform release.

Updates are performed by the Watchtower container, which checks for new images about every 5 minutes. The runtime probes its own ability to pull images and reports the result in its heartbeat, so the deployment page can show one of three pull-health states:

Solution:

1. Verify the Watchtower container is present and running: docker ps --filter "name=fleetera-watchtower-<alias>" — if it is missing, re-apply the compose (see "Docker Compose is stale" above)
2. If pull health shows Failing, the registry credential on the host is usually missing or expired. The runtime refreshes this credential automatically from the cloud on its heartbeat — check the runtime logs for credential errors: docker logs fleetera-runtime-<alias>
3. If pull health shows Probe unavailable, treat it as a blind spot rather than a failure — check that the runtime container is healthy and restart the stack if needed

Getting help

If you cannot resolve an issue using the steps above:

1. Collect the runtime logs: docker logs fleetera-runtime-<alias>
2. Note the deployment ID and the error messages from the event timeline
3. Contact Fleetera support with this information