In local-file mode: missing or invalid license_file, invalid signature, invalid fingerprint, or expired license outside the grace period.

Configure a valid license_file. For normal deployment, use the embedded public keys compiled into the binary.

The license is expired but still inside the 36-hour grace period.

Replace or renew the license before the grace period ends.

Gateway configuration, credentials, installation state, or the requested workload is invalid, or Gateway did not grant every requested component.

Check the startup error, verify the endpoint and authentication profile, confirm gateway_state_directory ownership and mode 0700, and give every target a valid component_instance_id. Gateway mode requires a full grant before startup continues.

Another exporter is using the state directory, or installation-id has unsafe permissions, ownership, type, or content.

Give each exporter installation its own persistent local state directory. Do not share or copy installation IDs, and do not delete an invalid identity to bypass the error; correct the deployment or restore the expected state.

The current lease expired, or Gateway returned an authoritative entitlement loss. Temporary failures permit work only while the existing lease remains valid.

Restore Gateway connectivity or entitlement, then restart the exporter. A terminal lease closure cannot be reopened by a late response.

The TOML file contains a key that the parser does not support.

Remove or rename the unsupported key. Use only documented top-level, [[targets]], and [[metric_scopes]] keys.

A [[targets]] entry does not define app.

Add app = "<app-name>" to every [[targets]] table.

A [[targets]] entry does not define server_key.

Add server_key = "<key>" to every [[targets]] table.

The requested target subtree is not fully subscribed and in sync.

Wait for readiness, verify the configured server_key, and rerun with debug = true or --debug for diagnostics.

The request does not include enough routing information.

Include server_key, or include app and instance. If multiple targets share the same app and instance, include server_key too.

A metric scope was selected, but multiple targets are configured.

Add the normal target-routing query parameters, such as ?server_key=82.

HTTP mode is enabled.

This is expected. When the HTTP listener is enabled, periodic Prometheus snapshots are no longer written to stdout.

Debug logging is disabled by default.

Set debug = true in TOML or pass --debug.

The archive does not match the host platform, a runtime library is missing, or the active-install link or service path is incorrect.

Use the supplied EL8 or EL9 archive for your host. Verify the active-install link and platform-specific binary name from Installation. Check missing-library errors with your system administrator. Ensure the service account has shared-memory access and uses an absolute license path.

In local-file mode, license validation failed or license_file is missing. For Gateway mode, use the Gateway troubleshooting items above.

Provide a valid customer license JSON file with --license-file or license_file.

The selected subtree is not fully subscribed and in sync yet, or no metric mappings match the selected app and paths.

Re-run with --debug, confirm the server key and app value, and verify that the selected root is discovered.

The requested target subtree is not ready, or the selected root, target object, or shared-memory server was lost.

Wait for initial sync, confirm the query routing parameters, and check diagnostics with --debug.

Multiple configured targets share the same app and instance.

Include server_key in the scrape query, such as /metrics?server_key=82.

This is expected behavior.

Query the HTTP endpoint instead. When HTTP mode is enabled, periodic snapshots are not written to stdout.

A required value is missing or an option value is invalid.

Check the configured targets or --server-key values, --metrics-interval is greater than 0, and --metrics-port is between 1 and 65535.

The requested target subtree is not ready yet.

Wait for the initial sync to complete. If it persists, verify server_key, app, instance, and shared-memory visibility.

Multiple targets are configured and the query does not include enough routing information.

Add server_key, or use a unique app and instance combination.

More than one target has the same app and instance.

Include server_key in the query.

CLI flags such as --server-key or --instance cleared the target tables and selected global target settings. Multiple global server keys still create multiple targets.

Remove the overriding CLI flags or move the target selection into TOML.

The selected app mapping, classes, seed path groups, or seed paths may not match the subscribed data.

Confirm the app value and review any classes, seed_path_groups, or seed_paths filters.

In local-file mode, license validation failed or license_file is missing. For Gateway mode, use the Gateway troubleshooting items above.

Configure a valid license_file. The exporter validates the license before opening the shared-memory pool.

Legacy m_qo_s_* aliases are no longer valid.

Use consumer_mqos_service_service, mqos_service_attributes, and mqos_service_datastreams.

Existing filters exclude the new classes or paths, or those objects are absent from the deployed ADH.

Review the new class/group selectors in Metric Configuration, target readiness, and scoped metric patterns. Verify the expected objects exist in the source.

The source value is blank or unsupported, the process timezone differs from the source, or a yearless value is interpreted in the current year.

Check the source value and scrape diagnostic comments. Match the exporter timezone to the application and validate populated dates, especially across year boundaries. Do not replace missing timestamp samples with zero.

The new RRCP driver and ThreadBindingStats CPU labels change existing series identities.

Review label matching, recording rules, joins, and cardinality using the ADH label changes. Allow for the transition from old to new series.

The Gateway deployment does not meet the Keystone Gateway v0.2.1 requirement, lacks the rrcp_trans entitlement, or the target lacks a valid stable component identity.

Use Keystone Gateway v0.2.1 for RRCP Trans licensing, provision the rrcp_trans entitlement, and set component_instance_id for every target. The complete workload must be granted before any target starts collecting.