# Troubleshooting

Use the items below to identify common LMC Exporter issues, understand likely causes, and apply the recommended resolution.

## Core Configuration

## Startup fails before LMC discovery

### Cause

Missing or invalid `license_file`, invalid signature, invalid fingerprint, or expired license outside the grace period.

### Resolution

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

## Expired license warning appears

### Cause

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

### Resolution

Replace or renew the license before the grace period ends.

## Startup fails with an unsupported TOML key error

### Cause

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

### Resolution

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

## Startup fails with \`missing required target app\`

### Cause

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

### Resolution

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

## Startup fails with \`missing required target server\_key\`

### Cause

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

### Resolution

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

## HTTP scrape returns \`503\`

### Cause

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

### Resolution

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

## Multi-target scrape cannot select a target

### Cause

The request does not include enough routing information.

### Resolution

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

## Scoped endpoint reports that target routing is required

### Cause

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

### Resolution

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

## No periodic snapshots appear on stdout

### Cause

HTTP mode is enabled.

### Resolution

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

## Too much diagnostic output is needed for investigation

### Cause

Debug logging is disabled by default.

### Resolution

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

## Quick Start

## \`make\` fails with compiler, platform, or LMC path errors

### Cause

The generated build settings do not match your environment.

### Resolution

Re-run `./configure`, provide the correct LMC install directory, target platform, and compiler path, then run `make` again in `src`.

## Startup fails before LMC discovery begins

### Cause

License validation failed or `license_file` is missing.

### Resolution

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

## No snapshot output appears

### Cause

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

### Resolution

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

## HTTP request returns \`503\`

### Cause

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

### Resolution

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

## HTTP scrape returns the wrong target or cannot disambiguate

### Cause

Multiple configured targets share the same app and instance.

### Resolution

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

## Metrics are not written to \`stdout\` in HTTP mode

### Cause

This is expected behavior.

### Resolution

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

## CLI command is rejected

### Cause

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

### Resolution

Check that `--server-key` is present, `--metrics-interval` is greater than `0`, and `--metrics-port` is between `1` and `65535`.

## Exporter Targets

## HTTP scrape returns \`503\`

### Cause

The requested target subtree is not ready yet.

### Resolution

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

## Scrape cannot identify a target

### Cause

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

### Resolution

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

## Scrape by \`app\` and \`instance\` is ambiguous

### Cause

More than one target has the same `app` and `instance`.

### Resolution

Include `server_key` in the query.

## TOML \`\[\[targets\]\]\` entries are ignored

### Cause

CLI flags such as `--server-key` or `--instance` switched the exporter to single-target mode.

### Resolution

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

## No metrics are returned for a configured target

### Cause

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

### Resolution

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

## Startup fails before discovery

### Cause

License validation failed or `license_file` is missing.

### Resolution

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

## Legacy ADH MQoS groups do not work

### Cause

Legacy `m_qo_s_*` aliases are no longer valid.

### Resolution

Use `consumer_mqos_service_service`, `mqos_service_attributes`, and `mqos_service_datastreams`.