Troubleshooting

Identify the affected layer first: client → Gateway → voice frontend / Backend Agent / frontend tools. Gateway connectivity does not prove model connectivity; an installed backend does not prove valid credentials.

Collect Basic Information

Check client and Gateway versions, run mode, and the selected voice frontend and Backend Agent. CLI commands:

qwenaudio --version
qwenaudio doctor
qwenaudio setup

Development builds include read-only doctor: it does not start models, backends, or microphones, or automatically change configuration. setup checks backend executables and integration components, not authentication, API keys, or quota. Without an active voice session, diagnostics report voice connectivity as unverified. Complete a real conversation to verify it.

Connections and Configuration

Symptom	Check and action
Gateway disconnected	Confirm it is running and the client uses its actual address and port. Desktop and CLI have independent runtimes by default; inspect the right instance.
Gateway connected, voice frontend unavailable	Check the voice service address, credentials, quota, and Provider error. Orb animation alone is not connectivity evidence.
Configuration changes have no effect	Find the file with qwenaudio config, check environment / source .env.local overrides, and restart the actual Gateway.
gateway restart says the service is not installed	It manages the user background service only. Restart terminal runs manually; apply settings or reopen Desktop.
Client occupied or taken over	Each user has one active connection per Gateway. Confirm takeover or close the other client.

See Run the Gateway and configuration directories.

Microphone and Playback

Symptom	Check and action
No microphone input	Check app / browser microphone permission, the system input device, mute, and sleep state.
Problems after plugging/unplugging a headset	Confirm system input/output switched to the intended devices. If needed, reopen the client and record the device model and switching sequence.
Text appears but there is no audio	Check output device, volume, and client playback state. For a local voice service, also inspect its TTS logs.
Speaker echo interrupts replies	Prefer half-duplex TUI on Linux / Windows; wear headphones for full-duplex without AEC.
Remote browser cannot access the microphone	Use trusted HTTPS and grant permission, not a plain remote HTTP address.

See TUI for audio modes. Sleep hides Desktop and stops microphone input to the voice frontend while retaining the Realtime connection. Wake-word detection runs locally when enabled.

Backends and Tools

• Backend execution fails: check installation with qwenaudio setup --backend <name>, then verify authentication and models in the backend's own interface.
• No backend model specified: the Gateway does not guess a default; it uses the Agent's configuration.
• Explicit model override fails: ACP backends must expose standard model configuration and accept the value, otherwise the override fails explicitly. See backend configuration for integration-specific settings such as DeepSeek / Muse.
• MCP command missing: check command and PATH. Restart after installing commands; gateway restart refreshes the path cache for a background service.
• MCP environment variable missing: put it in that Gateway's config.env, not a temporary export in another terminal.
• Library unavailable or import fails: enable it and use a Gateway-host path. Complex documents also require isolated conversion support.

See MCP configuration and Knowledge Library.

Remote Connections

For Tailnet, check that official Tailscale is online on both devices, they share a tailnet, access policies allow the connection, and Gateway HTTPS publication is ready. For LAN, check the subnet, firewall, and that the Gateway was started with --lan. For an external HTTPS endpoint, check certificates, reverse-proxy settings, and WebSocket forwarding. A connection code is displayed once; if it leaks, revoke that device and generate another one. See Remote Connections.

Logs and Reporting

Desktop exposes its log directory in Settings → Application → Logs. CLI logs default to ~/.config/qwaudio/state/logs; desktop-hosted Gateway logs use ~/.config/qwaudio/state/desktop/logs. Desktop Client logs use the logs/ subdirectory of its application data directory.

Session history retention

state/sessions/ contains recovery records, separate from diagnostic logs. Journals are not permanent audit archives:

• Each journal is compacted at 2,000 events or 8 MiB. Compaction prioritizes unfinished/scheduled tasks, undelivered results, recent messages and latest task snapshots. Sequence numbers are never reset.
• Up to 8 idle journals stay cached. The write queue is bounded as well; overload is reported rather than buffering indefinitely.
• Maintenance runs on writes, at most once every 10 minutes. Inactive journals expire after 30 days; oldest eligible files are also removed above 256 files or 128 MiB per Gateway state directory.
• Files containing recoverable work or undelivered results, and unreadable/corrupt files, are not removed automatically. They can keep the directory above its budget; session_journal.retention_protected reports this condition. If essential recovery data exceeds a single journal's budget, the append is rejected and logged, rather than deleting recovery state. Task persistence remains separate.

Compaction replaces files atomically and reports omitted history in the header's retention.discardedEvents. Deduplication covers retained events. Old removed history cannot be recovered from the journal; back up state/sessions/ separately if you need a permanent archive. Embedding applications can override these defaults when constructing SessionJournalRegistry.

Development builds can summarize a recorded turn:

qwenaudio doctor --turn <turnId>

See read-only diagnostics for bounds and limitations. When filing an Issue, include versions, OS, client / Gateway run mode, reproduction steps, time of occurrence, and relevant log excerpts. Do not include API keys, pairing codes, device tokens, full configuration files, or unreviewed private conversations.