# Troubleshooting

Start with the Plugins manager's state, error and per-plugin log. Preserve the
plugin version, host version, target architecture and exact failing action.
Use synthetic fixtures to produce a shareable reproduction.

Host 0.8.5 adds **Copy diagnostics**, timestamps, named UI errors, request/panel
context, affected properties and revision-conflict explanations. SDK pre.3 adds
completion logging helpers. See [actionable diagnostics](SDK-PRE3.md) for code
and for resolving stale timer/completion revisions without overwriting user input.

## Build and load problems

| Symptom | Check |
|---|---|
| CMake cannot find EpicTunerSDK | Point `CMAKE_PREFIX_PATH` at the extracted SDK root, not its include directory |
| CMake rejects the SDK version | Change a preview `0.x` package request to `1`; use a new build directory |
| Compiler lacks C++20 | Use a supported native compiler and `EpicTuner::SDKCpp` |
| Query symbol missing | Use `ET_PLUGIN` or the C export/calling convention; inspect `et_plugin_query` |
| Library fails to load | Match OS/architecture and inspect missing native runtime dependencies |
| Development plugin is absent | Supply both `--plugin-development` and the explicit absolute manifest path |
| All plugins stay stopped | Check `--safe-mode` and the plugin's enablement/license state |
| Wrong identity or missing grant | Match manifest ID/capabilities with the binary declaration |
| Image unavailable | Use an inventoried package-relative asset and copy it into development layout |

## Asynchronous API errors

An immediate error means no completion was queued. An immediate `ET_OK` means
the operation was queued; inspect its terminal completion. Keep callback owners
alive and never retain borrowed reply strings/items.

For `ET_ERROR_STATE`, check the callback thread and plugin/project lifecycle.
Host services are dispatcher-only. A background job may compute and observe its
cancellation token; it cannot call UI/read/log services.

For `ET_ERROR_LIMIT`, reduce batch size, page metadata, coalesce display updates,
and wait for outstanding completions. Do not spin or flood retries.

For stale handles or conflicts, discard the old preview/subscription and obtain
new context. Read project generation, tune definition, revision and stored values
again. Recompute the proposal. Never retry a timed-out Apply automatically.

## UI problems

Use stable namespaced panel IDs and unique node IDs. Each node's parent must
exist and the tree must be bounded and acyclic. Match property types from
[UI.md](UI.md). On patch rejection, keep the last valid model and report the
error; do not manufacture a new revision by incrementing a local guess.

If a panel becomes disabled, inspect worker failure first. A blocking callback
can trigger heartbeat termination. Close and restart through the host; restored
panel visibility does not replay button actions.

## Live data and logs

Disconnected, stale or invalid data is not zero. Test `ET_READ_VALID` and stale
flags before using a number. Expose sequence gaps to the user. Display
subscriptions intentionally coalesce updates; analysis subscriptions still have
finite buffers and must handle overflow.

Open logs through EpicTuner before enumerating them. Log IDs and selected channel
IDs belong to the current host context. A replaced/closed log cancels reads.
The analyzer fixtures provide exact expected means for a known-good comparison.

## Signing and activation

A publisher key and an issuer key have different roles. Trust each explicitly
for its purpose. Hash mismatch means a payload changed after signing; rebuild
and sign a new package rather than disabling verification.

An offline response must match the current installation, challenge nonce,
product and version rights. Export a fresh challenge after reinstallation or
another activation request. For subscriptions, inspect expiry and lease/grace
status. The test issuer accepts loopback HTTP; production activation requires
HTTPS.

## Build a useful bug report

Include the compiler/target, manifest, minimal source, synthetic fixture and
exact steps, together with relevant plugin diagnostics. Remove activation
secrets, private tune/INI data and captured customer logs. State whether the issue
reproduces in the checker, the development host, or the installed signed package.