Troubleshooting

This page covers common issues you may encounter with edge deployments and how to resolve them.

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.

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

Connectivity

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 bootstrap script output on the edge server for errors
2. Verify Docker containers are running: docker ps
3. Check the config agent logs: docker logs fleetera-config-agent
4. Ensure the server has internet access for the VPN connection

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. This can happen due to:

• Network connectivity loss at the site
• Docker containers stopped or crashed
• Server reboot or shutdown

Solution:

1. Check that the edge server is powered on and connected to the network
2. Verify Docker containers are running: docker ps
3. Restart the containers if needed: docker compose up -d
4. Check the config agent logs for errors: docker logs fleetera-config-agent
5. Verify the VPN connection is active

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 is not running.

Solution:

1. On the edge server, verify the VPN client is running and connected
2. If the VPN client is not running, restart the edge gateway services: docker compose up -d
3. Verify the config agent container is running and sending heartbeats

Configuration sync

Sync status shows Error

Symptom: The config sync status card shows an error state.

Cause: The config agent failed to apply the edge configuration. Common reasons include invalid device profiles or unreachable edge services.

Solution:

1. Check the error message displayed in the config sync status card
2. Review the config agent logs: docker logs fleetera-config-agent
3. Verify Fleetera Edge core services are running: docker ps
4. Try publishing the configuration again from the deployment detail page

See Error Handling for detailed information about sync errors.

Sync status stuck on Applying

Symptom: The config sync status remains in the "Applying" state for an extended period.

Cause: The config agent started applying the configuration but did not report the result. This can happen if the agent crashed during application or lost connectivity.

Solution:

1. Check the config agent logs for errors
2. Restart the config agent container: docker restart fleetera-config-agent
3. The agent will re-poll for configuration changes on the next cycle (every 30 seconds)

Config not reaching the edge

Symptom: You publish a configuration but the edge gateway does not pick it up.

Cause: The config agent polls for changes every 30 seconds. If the gateway is offline or the agent is not running, changes will not be applied.

Solution:

1. Verify the deployment is Online
2. Wait up to 30 seconds for the next poll cycle
3. Check the config agent logs to confirm it is polling
4. Ensure the VPN connection is active

Edge services

Edge containers not starting

Symptom: Some or all Fleetera Edge containers fail to start after bootstrap.

Cause: Insufficient system resources, port conflicts, or Docker configuration issues.

Solution:

1. Check available memory: free -m (minimum 2 GB required)
2. Check available disk space: df -h (minimum 16 GB required)
3. Review Docker logs for the failing container: docker logs <container-name>
4. Check for port conflicts: docker ps -a and ss -tlnp

Data not flowing from devices

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

Cause: The device service cannot connect to the industrial data source, or the binding configuration is incorrect.

Solution:

1. Check the device service logs (for example, docker logs device-opcua)
2. Verify the connector endpoint is reachable from the edge server
3. Review the binding configuration for correct addresses
4. Test connectivity to the data source from the edge server (for example, using ping or a protocol-specific tool)

Getting help

If you cannot resolve an issue using the steps above:

1. Collect the config agent logs: docker logs fleetera-config-agent
2. Collect the Fleetera Edge service logs for relevant containers
3. Note the deployment ID and the error messages from the event timeline
4. Contact Fleetera support with this information