Documentation Grafana Cloud Instrument and send data Fleet Management Manage your fleet Collectors Troubleshoot Remote config errors

Troubleshoot remote configuration errors

When a configuration pipeline has an error, Grafana Fleet Management helps you identify the affected collectors in several ways:

• On the Inventory tab, collectors with pipeline errors have a red health status that indicates an error has occurred and they are unhealthy.
• You might also see error logs on the Logs tab in the collector details view. These logs report the collector’s failure to fetch the remote configuration.
• Finally, you can also use the Remote Configuration dashboard on the Health tab in the collector details view to monitor how successfully a collector loads its remote configuration over time. The dashboard includes panels for the last configuration load status, the load success rate, and configuration error logs. It’s useful for identifying intermittent remote configuration load failures or confirming that a fix has resolved an issue.

Troubleshoot with Grafana Assistant

When a collector has a configuration pipeline error, a Troubleshoot in Assistant icon appears beside its health status indicator on the Inventory tab. You can click this icon to open Grafana Assistant with the collector’s configuration and error details pre-loaded. The assistant automatically analyzes the errors, explains the root cause of each one, and suggests specific fixes with corrected configuration examples.

1. In your Grafana Cloud instance, click Connections > Collector > Fleet Management.
2. On the Inventory tab, find the collector with a red (Error) status.
3. Click the Troubleshoot in Assistant icon next to the status indicator. Grafana Assistant opens and automatically sends a prompt that analyzes the configuration errors.
4. Review the suggested fixes and apply them to the relevant pipeline(s) on the Remote configuration tab.

Manually troubleshoot configuration errors

You can also troubleshoot errors in the Fleet Management application manually. To learn more about a configuration error, go to the Configuration tab in the collector details view of an affected collector. When an error is present, you can see an expandable error panel that includes diagnostic details. Follow these steps to troubleshoot the configuration error without leaving the application.

1. In your Grafana Cloud instance, click Connections > Collector > Fleet Management.

2. On the Inventory tab, search, filter, or sort to find the affected collector.

3. Click on the collector ID to open the details view, which takes you directly to the Configuration tab.

4. If configuration errors are present, a Configuration error banner appears at the top of the tab. The banner includes an expandable list of individual errors with diagnostic details, including:

   • Error messages describing what went wrong.
   • Line and column numbers indicating where each error occurs in the remote configuration.

5. Use the tabs to switch between the Effective config and Server config views. The effective configuration shows the last valid configuration the collector is still running despite the error. The server configuration shows the latest version that contains the error. Comparing the two views helps you identify what changed and caused the failure.

6. In the Server config view, find the line that corresponds to the error.

7. Scan backward in the configuration until you find the name of the erroring pipeline. Pipelines are named in a declare block. For example, the self-monitoring logs pipeline for Linux systems is named like this:

   Alloy Copy

   declare "self_monitoring_logs_linux" {

8. Once you know which pipeline caused the error and how to fix it, expand the Connected pipelines section and click on the pipeline in the list. The link takes you straight to the pipeline editor, where you can make the necessary changes.

Troubleshoot configuration rollout issues

When you save a configuration pipeline change, Fleet Management waits for the collector to poll and apply the new configuration. During this time, the collector details view shows an Applying status with a spinner icon and an informational banner on the Configuration tab.

If the collector doesn’t apply the configuration within two minutes, Fleet Management flags the rollout as potentially stuck and shows an Unresponsive warning status.

An unresponsive rollout typically means the collector is not running or is unable to reach the Fleet Management service. To diagnose the issue:

1. Verify that the collector process is running on the host or in the cluster.
2. In the collector details view, switch to the Logs tab and look for error messages such as msg="failed to fetch remote configuration from the API".
3. On the Health tab, select the Remote Configuration dashboard from the Alloy health dashboards dropdown menu. Check the panels for configuration load failures around the time the change was made.
4. Confirm that the collector has network connectivity to the Fleet Management service. If the collector is behind a firewall or uses a private endpoint, verify the network path is open.

Once the collector comes back online and successfully applies the configuration, the warning indicators clear automatically.