Troubleshoot device error codes

Red Hat Edge Manager uses structured error codes in device status responses to help you identify and resolve device failures. Each error code indicates the phase, component, and category of a failure so that you can take targeted corrective action.

Error message anatomy

Every error message follows a standardized 250-character format to help you quickly pinpoint the phase, component, and specific cause of a failure.

The error message format is as follows:

[timestamp] While <Phase>, <Component> failed [for "<Element>"]: <Category> issue - <STATUS_CODE>
Field Description Examples

Phase

The stage of the operation where the error occurred.

Preparing, ApplyingUpdate, Rebooting, RollingBack

Component

The specific system area affected.

os, config, applications, systemd

Element

The specific resource (file, service, or image).

/etc/app.conf, fleet-agent.service, quay.io/app

Category

The functional area of the failure.

Network, Security, Resource

Status Code

The standardized gRPC-based error code.

UNAVAILABLE, PERMISSION_DENIED, INTERNAL

Error reference and resolution

Use the following table to identify the root cause of a status code and the recommended next steps.

Category Status Code Common Causes Recommended Action

Network

UNAVAILABLE / DEADLINE_EXCEEDED

DNS failure, registry unreachable, or connection timeout. Image non-existent or inaccessible due to registry permissions.

Check device internet connectivity and firewall rules for registry access. Verify the image name/tag and registry-level access permissions.

Security

PERMISSION_DENIED / UNAUTHENTICATED

Invalid credentials, expired tokens, or insufficient permissions.

Verify registry credentials and ensure the device identity is valid.

Configuration

INVALID_ARGUMENT / FAILED_PRECONDITION

Syntax errors in YAML/JSON or missing mandatory fields. Invalid element, token, or path format.

Validate your configuration spec against the schema.

Filesystem

NOT_FOUND / ALREADY_EXISTS

Missing files, directory conflicts, or path errors.

Verify the existence of required local resources or mount points.

Resource

RESOURCE_EXHAUSTED

Disk full, Out of Memory (OOM), or CPU throttling.

Check device telemetry for disk usage and memory pressure.

System

INTERNAL / UNKNOWN

Unexpected system faults or unclassified errors.

See Deep dive debugging below to correlate with journal logs.

Rollback and failed operating system updates

If an operating system update fails, the device automatically rolls back to the previous version. The phase might be displayed as RollingBack; when rollback completes, the update condition reason is Error. The device does not retry the failed version automatically. For how to recognize a rollback and what to do next, see Troubleshooting operating system update rollback in the Additional resources section.

Deep dive debugging

While API status responses are sanitized for security, full error details — including stack traces and raw Go error chains — are preserved in the local device journal.

If you encounter an UNKNOWN or INTERNAL error, or if the status message is truncated, you can map the status code to the detailed log:

  1. Retrieve the device status, making sure to note the timestamp and component from the message field. 
    flightctl get device/<device-name> -o yaml
  2. Access the device logs.

    If you use the Flight Control web console, open the device Logs tab and retrieve logs with filters that include the failure time. For steps, see Viewing, streaming, and downloading device logs in the web console in the Additional resources section.

    If you have shell access on the device, search the local journal for the corresponding error context to see the unredacted failure:

    sudo journalctl -u flightctl-agent.service | grep "failed to reload systemd daemon"
Note

API responses are limited to 250 characters. For the full diagnostic context, including raw Go error strings and detailed stack traces, refer to the local logs on the device.

 Warning

Local journal logs contain unredacted error details that can include file paths, configuration values, and other sensitive information. Do not share raw journal output in public forums or unsecured channels without first reviewing and redacting sensitive content.