Introduction

Grafana uses YAML provisioning files to automatically configure datasources, dashboards, alert rules, and notification policies on startup. When a provisioning file contains a YAML syntax error -- such as incorrect indentation, tabs instead of spaces, or unquoted special characters -- Grafana may silently skip the file or partially apply it. This results in missing datasources, dashboards, or alert rules without any obvious error indication.

Symptoms

  • Expected datasources do not appear after Grafana restart
  • Provisioned dashboards are missing from the Grafana UI
  • Grafana logs show failed to load provisioning file at debug level but no errors at info level
  • Provisioning file changes have no effect on Grafana configuration
  • Error message: yaml: line 15: did not find expected key (only visible in debug logs)

Common Causes

  • YAML indentation error using spaces and tabs mixed
  • Unquoted strings containing special characters (colons, braces, brackets)
  • Missing required fields in the provisioning file structure
  • File encoding issue (UTF-8 BOM at the start of the file)
  • Duplicate keys in the YAML file silently overwriting earlier values

Step-by-Step Fix

  1. 1.Enable debug logging to surface provisioning errors: See the actual YAML parse error.
  2. 2.```ini
  3. 3.# grafana.ini
  4. 4.[log]
  5. 5.mode = console file
  6. 6.level = debug
  7. 7.`
  8. 8.Validate the provisioning YAML file syntax: Use a YAML linter.
  9. 9.```bash
  10. 10.# Install yamllint
  11. 11.pip install yamllint
  12. 12.yamllint /etc/grafana/provisioning/datasources/datasources.yml
  13. 13.`
  14. 14.Fix common YAML syntax issues: Correct the file format.
  15. 15.```yaml
  16. 16.# WRONG: tab indentation and unquoted colon
  17. 17.apiVersion: 1
  18. 18.datasources:
  19. 19.- name: Prometheus
  20. 20.url: http://prometheus:9090 # colon in comment is fine
  21. 21.type: prometheus
  22. 22.access: proxy

# CORRECT: spaces, proper indentation apiVersion: 1 datasources: - name: Prometheus url: "http://prometheus:9090" type: prometheus access: proxy ```

  1. 1.Verify provisioning file structure matches Grafana requirements: Check the expected schema.
  2. 2.```bash
  3. 3.# Validate against Grafana's provisioning schema
  4. 4.cat /etc/grafana/provisioning/datasources/datasources.yml
  5. 5.# Ensure apiVersion, datasources array, and required fields are present
  6. 6.`
  7. 7.Restart Grafana and verify provisioning applied: Confirm resources are created.
  8. 8.```bash
  9. 9.systemctl restart grafana-server
  10. 10.# Check Grafana UI for provisioned datasources and dashboards
  11. 11.curl -s http://admin:admin@localhost:3000/api/datasources | jq '.[].name'
  12. 12.`

Prevention

  • Use YAML linting in CI/CD pipelines that deploy Grafana provisioning files
  • Always quote string values that may contain special characters (colons, braces)
  • Use 2-space indentation consistently -- never mix tabs and spaces
  • Test provisioning files in a staging Grafana instance before production deployment
  • Monitor Grafana provisioning logs at debug level during deployment
  • Version control all provisioning files and review changes for YAML syntax correctness