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 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. 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.