@cryptotaxi247 / netdata-1 / commits / 51fcf3aa3

docs: add HTTP 412 troubleshooting and publish bearer token protection docs on Learn (#22044)

* docs: add troubleshooting for HTTP 412 error when editing alert configs Add troubleshooting section to dynamic-configuration.md documenting HTTP 412 error cause (missing bearer token authentication) when editing alert configurations, clarifying it is not a schema validation error, and providing resolution steps. * docs: correct HTTP 412 troubleshooting cause from permissions to missing bearer token * docs: remove manual TOC from dynamic-configuration.md The documentation platform auto-generates a dynamic TOC from page headings, so the manually maintained Table of Contents is redundant. * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> * Update map.yaml * Update secure-your-netdata-agent-with-bearer-token.md * Update dynamic-configuration.md * Update secure-your-netdata-agent-with-bearer-token.md * Update docs/netdata-agent/configuration/dynamic-configuration.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: nedi-app[bot] <bot@netdata.cloud> Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

nedi-app[bot] committed Apr 6, 2026 at 08:54 UTC 51fcf3aa3874280ad8906cf3ba832588af381939
3 files changed +36 -11
docs/.map/map.yaml
+3
@@ -203,6 +203,9 @@ sidebar:
203 label: Web Server Reference
204 edit_url: https://github.com/netdata/netdata/edit/master/src/web/server/README.md
205 description: The Netdata Agent's local static-threaded web server serves dashboards and real-time visualizations with security and DDoS protection.
206 + - meta:
207 + label: Bearer Token Protection
208 + edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md
209 - meta:
210 label: Running the Agent behind a reverse proxy
211 edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/README.md
docs/netdata-agent/configuration/dynamic-configuration.md
+30 -8
@@ -1,13 +1,5 @@
1 # Dynamic Configuration Manager
2
3 -## Table of Contents
4 -
5 -- [Overview](#overview)
6 -- [Quick Access Methods](#quick-access-methods)
7 -- [Getting Started](#getting-started)
8 -- [Collectors](#collectors)
9 -- [Multi-Node Deployment](#multi-node-deployment)
10 -
3 ## Overview
4
5 :::important
@@ -273,6 +265,36 @@ This feature is particularly valuable for managing large infrastructures where m
265
266 :::
267
268 +## Troubleshooting
269 +
270 +### HTTP 412 Error When Editing Alert Configurations
271 +
272 +If you receive an **HTTP 412 error** with a message like "Request failed with status 412" when editing alert configurations, this indicates an **authentication issue**, not a schema validation error.
273 +
274 +:::important
275 +
276 +In Netdata, HTTP 412 is used to indicate that an authorization bearer token was required but was not present in the request. This differs from the generic HTTP 412 "Precondition Failed" response.
277 +
278 +:::
279 +
280 +**Common causes:**
281 +
282 +1. **Bearer token protection enabled** - Your agent requires Cloud authentication for API access
283 +2. **Cloud connection lost** - Agent disconnected from Netdata Cloud
284 +3. **Session expired** - Bearer token has expired (tokens expire after 24 hours)
285 +4. **Missing browser authentication state** - Your browser is no longer sending a valid Cloud bearer token with the request
286 +
287 +**Resolution steps:**
288 +
289 +1. **Verify claim and Cloud connection**: Check `http://IP:19999/api/v3/info` and inspect the `cloud` section. Use `cloud.status` to verify whether the Agent is connected to Netdata Cloud, and if it is not `online`, inspect `cloud.reason` for the failure details.
290 +2. **Re-authenticate**: Log out and log back into Netdata Cloud to refresh your bearer token.
291 +3. **Verify bearer token protection setting**: If enabled in `netdata.conf`, ensure you're accessing the agent through a Cloud-authenticated session.
292 +4. **Check permissions only if you get HTTP 403**: If the request changes from HTTP 412 to HTTP 403 after re-authenticating, ensure you have Admin or Manager role in the space containing the agent.
293 +
294 +For more information, see [Secure Your Netdata Agent with Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md).
295 +
296 +---
297 +
298 Experience the efficiency and power of the Dynamic Configuration Manager in Netdata today. Whether you're managing a handful of nodes or a vast infrastructure, this feature will make your monitoring and alerting tasks smoother and more intuitive.
299
300 Developing with dynamic configuration? [Click here](https://learn.netdata.cloud/docs/developer-and-contributor-corner/dynamic-configuration/).
docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md
+3 -3
@@ -123,9 +123,9 @@ Example combining bearer token with IP restrictions:
123
124 **Users can't authenticate:**
125
126 -- Verify the agent is claimed: Check `http://your-server:19999/api/v3/info` for `cloud-available: true`
127 -- Verify ACLK is connected: Look for "ACLK" status in the agent logs
128 -- Ensure users have access to the same Cloud space as the agent
126 +- Verify the Agent is claimed and connected to Cloud: Check `http://your-server:19999/api/v3/info` and inspect the `cloud` section. Use `cloud.status` to verify whether the agent is connected to Netdata Cloud, and if it is not `online`, inspect `cloud.reason` for the failure details
127 +- If needed, run `sudo netdatacli aclk-state` to diagnose the ACLK connection
128 +- Ensure users have access to the same Cloud Space as the Agent
129
130 **Token expired errors:**
131