Troubleshooting

Symptom	Check
EPICS headers/libraries not found	Build Base first; set EPICS_BASE and EPICS_HOST_ARCH to that installation. See build discovery.
Qt modules or build tools missing	Install matching Widgets, Network, PrintSupport, and Multimedia development files; tests also need Qt Test. Use QT_VERSION=5 or 6 consistently and matching moc/rcc.
Cannot open a display	Use the native GUI session or a working X11 display. Use --validate for a headless syntax check; test targets supply offscreen mode where appropriate.
Channel remains ERROR	Verify the PV name, IOC availability, CA address environment, and read access. -debug -noerrorpopup exposes connection/access diagnostics on stderr.
Acknowledgement or output PV does not change	Check local/global/passive mode and IOC write access. Failed acknowledgements remain visible; manual ACKT changes require an explicit retry.
Cannot open logs or lock files	Create the parent directory and check permissions on the selected files and checkpoint sidecar. A failed log destination change preserves the current destination.
Sound fails	Check the audio path, Qt Multimedia plugins/backend, output device, Silence Forever, and beep threshold. Muted fixture playback verifies decoding, not speaker output.
Helper or visual tests fail	Check the test prerequisites; missing rpcbind, legacy executables, softIoc, or X11 are failures, not skipped coverage.