Error Handling

When the config agent on the edge gateway fails to apply a configuration, it reports the error back to the cloud. The sync status changes to Error, and the error details appear in the config sync status card on the deployment detail page.

Error codes

Error structure

Each error includes the following fields:

Common errors

Download errors

Network connectivity issues

The agent cannot reach the cloud API to download the configuration bundle. This typically occurs when:

• The VPN connection is down
• The edge server has lost internet connectivity
• A firewall is blocking outbound HTTPS traffic

Resolution: Check the VPN connection on the edge server and verify internet access.

Apply errors

Invalid device profile

The generated device profile failed validation. This can happen when:

• A variable binding references a data type that Fleetera Edge does not support
• A device resource name contains invalid characters

Resolution: Review the variable bindings for the affected connector and verify that the data types and variable keys are valid.

Edge service unavailable

The agent cannot reach the core-metadata service to apply the configuration. This occurs when:

• The core-metadata container is not running
• The container is still starting up after a restart

Resolution: Check that the Fleetera Edge containers are running (docker ps) and wait for core-metadata to become ready. The agent retries automatically on the next poll cycle.

Conflict during update

The agent attempted to create a resource that already exists. The agent uses a create-or-update pattern (creating first, then updating on conflict), but unexpected states in Fleetera Edge can cause issues.

Resolution: This is usually transient. The agent will retry on the next poll cycle. If it persists, restart the edge containers (docker compose restart).

Error recovery

The config agent is designed to recover from errors automatically:

1. Errors are recorded — the agent reports the error to the cloud, and the sync status changes to Error
2. Polling continues — the agent does not stop polling after an error; it checks for changes every 30 seconds
3. Retry on next cycle — if the underlying issue is resolved (for example, Fleetera Edge comes back online), the agent applies the configuration on its next poll cycle
4. New publish clears errors — publishing a new configuration resets the sync status to Pending, and the agent will attempt the new configuration

Viewing errors

In the platform

Navigate to the deployment detail page and check the Config Sync Status card. When the sync status is Error, the card displays the first error with its message, code, and the affected resource.

On the edge server

You can view the config agent logs directly on the edge server:

docker logs fleetera-config-agent

The agent logs each step of the sync process, including the error details and the edge API responses.

In the event timeline

The deployment event timeline records error events with the error message. Review the timeline on the deployment detail page for a chronological view of what occurred.

Preventing errors

To minimize configuration sync errors:

• Verify bindings — ensure that variable bindings have valid addresses and compatible data types before publishing
• Check connectivity — confirm that the edge gateway is Online before publishing configuration changes
• Monitor edge health — use the heartbeat service status information to verify that all edge containers are running
• Use auto-publish cautiously — for production deployments, consider disabling auto-publish so you can review changes before they reach the edge