WebSocket 1009 error when starting live transcription on M1 Mac

[hyper-charlie]

Problem

Live transcription fails to start with WebSocket error code 1009 (connection going away). User cannot transcribe recordings or live audio.

Environment

• Platform: macOS (M1)
• App Version: 1.0.17
• Build: 866a098
• Transcription Model: Char Parakeet v3 (local) / also wants to use external AI provider API

Steps to Reproduce

1. Open Hyprnote
2. Start a live recording or attempt to transcribe a local file
3. Transcription fails with WebSocket 1009 error

Expected Behavior

Transcription should start successfully and process audio in real-time.

Additional Context

User has tried both local LLM and API provider connections with same error. This appears to be a connection failure on startup.

Related Issues

• Local speech-to-text model connection fails on macOS M1 Pro during recording start #4473: Local speech-to-text model connection fails on macOS M1 Pro during recording start
• Local transcription frozen after 45-min recording; service won't recover #4552: Local transcription frozen after 45-min recording; service won't recover

[devin-ai-integration]

Codebase Context for WebSocket 1009 Error

Clarification on Close Code 1009

WebSocket close code 1009 = "Message Too Big" (not "connection going away", which is 1001). This means one side of the WebSocket connection received a message exceeding its maximum allowed size and terminated the connection. This distinction is important for narrowing down the root cause.

---

Relevant Files & Architecture

The live transcription pipeline has several layers, and the 1009 error could originate from any of them:

1. Desktop Client → Local STT Server (most likely path for local models)

• plugins/local-stt/src/ext.rs — Manages local STT server lifecycle. On aarch64 (M1), uses the "internal2" path (Internal2STTActor) which runs an in-process axum server with hypr_transcribe_cactus::TranscribeService.
• plugins/local-stt/src/server/internal2.rs — The internal2 actor starts an axum server on a random local port with axum::serve(listener, router). No WebSocket configuration (max message size, max frame size) is set — it uses axum's defaults.
• crates/local-stt-server/src/lib.rs — Standalone local STT server, also uses default axum WebSocket config.
• crates/transcribe-cactus/src/service/streaming/service.rs — The TranscribeService handles WebSocket upgrades via WebSocketUpgrade::from_request_parts(). Again, no explicit message size limits are configured on the upgrade.
• crates/transcribe-cactus/src/service/streaming/session.rs — Handles the WebSocket session loop. Receives audio as binary messages, sends back JSON transcript responses. The handle_ws_message method processes incoming audio chunks.

2. Desktop Client WebSocket Layer

• crates/ws-client/src/client.rs — WebSocketClient::from_audio() establishes the WS connection via tokio-tungstenite. Audio data is sent as binary messages. No max_message_size or max_frame_size is configured on the tungstenite connection either.
• crates/ws-client/src/retry.rs — Connection retry with configurable policy. Desktop uses connect_timeout: 4s, max_attempts: 2, retry_delay: 1s (see desktop_connect_policy() in adapters.rs:143-149).
• crates/ws-client/src/error.rs — Error::RemoteClosed { code, reason } variant captures close codes. A 1009 close frame would be captured here and propagated as a StreamError to the listener actor.

3. Listener Actor (orchestration layer)

• crates/listener-core/src/actors/listener/adapters.rs — spawn_rx_task() dispatches to the correct adapter based on URL. For local Cactus models, uses CactusAdapter. Connects via owhisper_client::ListenClient.
• crates/listener-core/src/actors/listener/mod.rs — Handles StreamError messages by stopping with DegradedError::StreamError, which surfaces to the UI as a connection error.
• crates/listener-core/src/actors/listener/stream.rs — process_stream() forwards responses and errors from the WS stream to the listener actor. A StreamError breaks the loop.

4. Proxy Path (for external API providers)

• crates/transcribe-proxy/src/relay/handler.rs — WebSocketProxy relays between client and upstream provider. Also no explicit message size limits.
• crates/transcribe-proxy/src/routes/streaming/mod.rs — Route handler for streaming STT WebSocket upgrade.

---

Key Observation: No Explicit WebSocket Size Limits Anywhere

A grep for max_message_size, max_frame_size, max_write_buffer_size across the entire Rust codebase returns zero results. This means all WebSocket endpoints rely on library defaults:

• tungstenite default max_message_size = 64 MB
• axum::extract::ws default max_message_size = 64 MB (wraps tungstenite)

Audio chunks at 16kHz mono should be small (a few KB per chunk at 300ms intervals), so hitting 64 MB seems unlikely. However, if there's an issue with message framing or encoding on the client side, or if the audio pipeline sends accumulated data in a single large message, this could trigger 1009.

---

Potential Causes

1. Sidecar/Model initialization race: On M1, the internal2 server may not be fully ready when the WS client connects. The health check in ext.rs:137-147 verifies the server URL exists, but doesn't confirm the model is loaded. If the model loading fails or is slow, the server might reject the WebSocket upgrade or close with an error. The TranscribeService loads the model synchronously during the first WebSocket request (build_model at service.rs:96).

2. External STT sidecar startup: For the external server path (ExternalSTTActor), the sidecar process has retry logic with 20 attempts at 500ms intervals (external.rs:207-217). If the sidecar fails to start, the connection error surfaces, but the close code might not be 1009.

3. Audio encoding mismatch: The process_incoming_message function in the cactus streaming session expects specific audio formats (mono f32 or interleaved dual-channel). If the client sends audio in an unexpected format or size, it could cause the server to close the connection.

4. Connection replacement: The ConnectionManager in ws-utils/src/manager.rs cancels the previous connection when a new one is acquired. If multiple connection attempts happen rapidly (e.g., due to UI retries), an older connection gets cancelled, which could manifest as an unexpected close.

---

Recent Relevant Changes

• 6ac06c35e (Mar 7) — "Improve ws-client retry/error handling and wire connect policy into listener clients (Improve ws-client retry/error handling and wire connect policy into listener clients #4453)" — Major refactor of WS error handling and retry logic. Added WebSocketConnectPolicy to desktop clients. This is the most relevant recent change.
• b636b870d (Mar 9) — "various refactor and HOTFIX for transcribe-proxy" — Significant refactor of the proxy relay and channel split logic.
• 400d3b18c — "chore: update cactus to v1.11 with timestamp support (chore: update cactus to v1.11 with timestamp support #4537)" — Cactus model update.
• afd405fd2 — "handle backpressure in ws-utils" — Backpressure handling changes.

---

Suggested Investigation

1. Check logs for the exact close frame reason string alongside code 1009 — the RemoteClosed error captures both code and reason, which would indicate which end is sending the 1009.
2. Verify model loading on the user's M1 — if the Cactus/Parakeet model files are corrupted or incompletely downloaded, build_model would fail at service.rs:96-106, though this should return an HTTP 500 rather than a WS 1009.
3. Check if the error occurs during connection or during streaming — if it's on connection, focus on the retry/connect path; if it's during streaming, focus on message size or encoding issues.
4. Consider adding explicit max_message_size configuration to the axum WebSocket upgrades to provide clearer error messages and prevent unexpected 1009s from library defaults.

[hyper-charlie]

Additional Report:

User encountering the same WebSocket 1009 error when using models other than Whisper Small with the Char provider.

Environment:

• Device: Apple laptop with M4 Max chip
• Platform: macOS 26.3.1
• App Version: 1.0.17
• Build: 866a098

Error Details:

• Initial error: external_stt_init_failed: Request(reqwest::Error) with connection refused on http://localhost:61611/v1/init
• WebSocket error: RemoteClosed(code=Some(1009), reason=)

Reproduction:

1. Configure Char as transcription provider
2. Select any model other than Whisper Small
3. Attempt to transcribe a recording
4. Transcription fails with WebSocket 1009 error

[m13v]

the 1009 (message too big) on M1 is almost certainly a model loading race condition, not an actual oversized message. we hit this exact pattern building local STT pipelines. what happens is the websocket connection opens before the model is fully loaded into memory, the server sends an incomplete or error response that gets misframed, and the client interprets it as 1009. the fix that worked for us was adding a readiness endpoint that checks both the HTTP server AND model initialization state, then only allowing websocket upgrades after the model reports ready. for the specific M1 issue with models other than Whisper Small, larger models take significantly longer to load and the Neural Engine compilation step on first use adds several seconds. the 4s connection timeout in the retry policy might be too tight for that initial model load. worth bumping to 15-20s for the first attempt only.

[m13v]

our local transcription service that handles model loading, readiness checks, and the audio pipeline on Apple Silicon: https://github.com/m13v/fazm/blob/main/Desktop/Sources/TranscriptionService.swift