Troubleshooting

Troubleshoot common issues

Fix recording, permissions, transcript quality, API, and media capture issues.

Audience: Users who hit a blocked workflow and need a calm recovery path.

Time: 16 minutes

Level: All levels

Scenario

Start with the workflow this guide is designed for before moving into the steps.

As a user preparing a real workflow, I want a checklist for common failures so I can fix the problem without losing the recording or exposing private data.

You can identify the likely failure layer and collect safe details for support.

Steps

Classify the failure

Decide whether the problem is capture, upload, transcription, template output, API auth, or review.

You can name the first failing step.

You avoid changing unrelated settings at random.

Collect safe support details

Capture screenshots or logs that show the error, but redact keys, private names, and raw sensitive transcripts.

No credentials appear in the support details.

The timestamp and failing action are visible.

Retry the smallest safe step

Use a small sample recording or placeholder API request instead of repeating the full high-stakes workflow.

The retry is small enough to repeat.

The result tells you whether the failure moved or stayed.

Details

Failure map

Most issues become easier once you separate where the failure happened.

Capture: microphone, permissions, file format.
Processing: upload, transcription, long-audio behavior.
Output: template quality, dictionary terms, review state.
Automation: auth header, endpoint, secret handling.

Recover a stopped Desktop recording

A stopped Desktop capture with actual audio is retained in local Records before later processing decisions. If speech detection, the network, transcription, or AI processing fails, check Records before making another recording.

Open Records and locate the item created when you stopped recording.
Replay or inspect the retained audio before retrying transcription.
If no local item exists, record the time and capture state for support without exposing private audio.

Confirm whether AI optimization ran

Desktop can start one AI optimization while final speech is settling, then reuse that prefetched result when the recording finishes. A fast final response therefore does not mean AI was skipped, and it should not create a second workflow run.

First check whether the saved result is marked optimized, raw fallback, pending, or failed; these states are different.
After a successful Records retry, desktop diagnostics should preserve the actual n8n workflow name, workflow ID, and call ID returned by the server.
For support, include the timestamp and the redacted workflow/call identifiers from diagnostic logs. Never include transcript text, API keys, or webhook URLs.
A prefetch cache hit should reuse the first workflow call and skip a duplicate dispatch.