Error Handling

When the edge gateway fails to apply a configuration, the sync status changes to Error and the failure details appear in the Config Sync card on the deployment's Configuration page.

Common failure modes

Gateway cannot reach the cloud

The Edge Runtime cannot fetch the new configuration. 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 (tailscale status) and verify internet access. The gateway keeps running its last applied configuration in the meantime — the runtime caches it on disk, so even a restart during the outage comes back with the known-good configuration.

Driver cannot apply a binding

A connector or binding change is applied to the runtime's in-process drivers, but the driver cannot act on it — for example, an unreachable endpoint or an invalid protocol address.

Resolution: Driver-level problems surface on the deployment's Monitoring page, where each connector's driver reports its status (connected, disconnected, or error) and last error message. Review the binding configuration for the affected connector and verify the endpoint is reachable from the edge server.

Runtime container is down

If the runtime container has stopped, nothing polls for configuration and the status stays Pending rather than erroring.

Resolution: On the edge server, check docker ps for fleetera-runtime-<alias> and restart the stack from the gateway's install directory if needed. See Troubleshooting.

Error recovery

The sync loop is designed to recover automatically:

1. Polling continues — the runtime does not stop polling after a failure; it checks for changes every 30 seconds
2. Retry on next cycle — if the underlying issue is resolved, the configuration is applied on the next poll cycle
3. New publish clears errors — publishing a new configuration resets the sync status to Pending, and the runtime attempts the new configuration

Viewing errors

In the platform

Open the deployment's Configuration page and check the Config Sync card. When the sync status is Error, the card displays a Sync Error block with the details.

On the edge server

You can view the runtime logs directly on the edge server:

docker logs fleetera-runtime-<alias>

The runtime logs each step of the sync process, including configuration polls, driver changes, and errors.

In the event timeline

The deployment event timeline on the Overview page records error events with the error message, giving 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
• Preview before publishing — use Preview Changes to inspect exactly what will be sent to the gateway
• Use auto-publish deliberately — for production deployments, consider disabling auto-publish so you can review changes before they reach the edge