Exported errors

Cloud-init makes internal errors available to users for debugging. These errors map to logged errors and may be useful for understanding what happens when cloud-init doesn’t do what you expect.

Aggregated errors

When a recoverable error occurs, the internal cloud-init state information is made visible under a top level aggregate key recoverable_errors with errors sorted by error level:

$ cloud-init status --format json
{
  "boot_status_code": "enabled-by-generator",
  "config": {...},
  "datasource": "",
  "detail": "Cloud-init enabled by systemd cloud-init-generator",
  "errors": [],
  "extended_status": "degraded done",
  "init": {...},
  "last_update": "",
  "recoverable_errors":
  {
    "WARNING": [
      "Failed at merging in cloud config part from p-01: empty cloud config",
      "No template found in /etc/cloud/templates for template source.deb822",
      "No template found in /etc/cloud/templates for template sources.list",
      "No template found, not rendering /etc/apt/soures.list.d/ubuntu.source"
    ]
  },
  "status": "done"
}

Reported recoverable error messages are grouped by the level at which they are logged. Complete list of levels in order of increasing criticality:

WARNING
DEPRECATED
ERROR
CRITICAL

Each message has a single level. In cloud-init’s log files, the level at which logs are reported is configurable. These messages are exported via the 'recoverable_errors' key regardless of which level of logging is configured.

Per-stage errors

The keys errors and recoverable_errors are also exported for each stage to allow identifying when recoverable and non-recoverable errors occurred.

$ cloud-init status --format json
{
  "boot_status_code": "enabled-by-generator",
  "config":
  {
    "WARNING": [
      "No template found in /etc/cloud/templates for template source.deb822",
      "No template found in /etc/cloud/templates for template sources.list",
      "No template found, not rendering /etc/apt/soures.list.d/ubuntu.source"
    ]
  },
  "datasource": "",
  "detail": "Cloud-init enabled by systemd cloud-init-generator",
  "errors": [],
  "extended_status": "degraded done",
  "init":
  {
    "WARNING": [
      "Failed at merging in cloud config part from p-01: empty cloud config",
    ]
  },
  "last_update": "",
  "recoverable_errors":
  {
    "WARNING": [
      "Failed at merging in cloud config part from p-01: empty cloud config",
      "No template found in /etc/cloud/templates for template source.deb822",
      "No template found in /etc/cloud/templates for template sources.list",
      "No template found, not rendering /etc/apt/soures.list.d/ubuntu.source"
    ]
  },
  "status": "done"
}

Note

Only completed cloud-init stages are listed in the output of cloud-init status --format json.

The JSON representation of cloud-init boot stages (in run order) is:

"init-local"
"init"
"modules-config"
"modules-final"

Limitations of exported errors

  • Exported recoverable errors represent logged messages, which are not guaranteed to be stable between releases. The contents of the 'errors' and 'recoverable_errors' keys are not guaranteed to have stable output.

  • Exported errors and recoverable errors may occur at different stages since users may reorder configuration modules to run at different stages via cloud.cfg.

Where to next?

See here for a detailed guide to debugging cloud-init.