From 62a2ad9e7c63b8579feb1245fb60c63a0546a1ab Mon Sep 17 00:00:00 2001
From: mARTin-B78 <mail@martin-bierschenk.de>
Date: Mon, 21 Sep 2026 18:02:23 +0200
Subject: [PATCH] fix: pin upstream faster-qwen3-tts to avoid Transformers 5
 mismatch

Fresh builds cloned upstream main, which since v0.4.0 requires
Transformers 5 (qwen-tts-hf). qwen-asr then downgraded transformers to
4.57.6, breaking Qwen3TTSModel.from_pretrained at startup.

Pin upstream to 7cdef7e (v0.2.6, as in the released images) and pin
qwen-tts==0.1.1 / qwen-asr==0.0.6. FASTER_QWEN3_TTS_REF now accepts a
commit SHA, tag or branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 Dockerfile | 17 +++++++++++------
 README.md  |  6 ++++++
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index bb1afbb..231a3be 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -15,10 +15,13 @@ RUN apt-get update && \
 
 WORKDIR /app
 
-# Clone the upstream faster-qwen3-tts library
-ARG FASTER_QWEN3_TTS_REF=main
-RUN git clone --depth 1 --branch ${FASTER_QWEN3_TTS_REF} \
-    https://github.com/andimarafioti/faster-qwen3-tts.git /app
+# Clone the upstream faster-qwen3-tts library, pinned to a known-good commit.
+# Upstream >= v0.4.0 moved to Transformers 5 (qwen-tts-hf), which conflicts with
+# qwen-asr (pins transformers==4.57.6) and breaks model loading. Accepts a
+# commit SHA, tag or branch.
+ARG FASTER_QWEN3_TTS_REF=7cdef7e40195108b51a808f2ce5c7d5f3e235a79
+RUN git clone https://github.com/andimarafioti/faster-qwen3-tts.git /app && \
+    cd /app && git checkout --detach ${FASTER_QWEN3_TTS_REF}
 
 # Apply DGX Spark patches (non_streaming_mode=True, per-voice temperature/top_k/top_p)
 COPY patches/openai_server.patch /tmp/
@@ -36,8 +39,10 @@ RUN pip install --no-cache-dir torch torchvision torchaudio \
     --index-url https://download.pytorch.org/whl/cu130
 
 # Install faster-qwen3-tts and server dependencies
-RUN pip install --no-cache-dir -e ".[demo]"
-RUN pip install --no-cache-dir pydub soundfile uvicorn fastapi qwen-asr
+# Keep the Transformers 4 stack: qwen-tts pins transformers==4.57.3, qwen-asr
+# then moves it to 4.57.6 (same combination as the released images).
+RUN pip install --no-cache-dir -e ".[demo]" "qwen-tts==0.1.1" "huggingface-hub<1.0"
+RUN pip install --no-cache-dir pydub soundfile uvicorn fastapi "qwen-asr==0.0.6"
 
 EXPOSE 8000
 
diff --git a/README.md b/README.md
index 4c7c055..a5820a5 100644
--- a/README.md
+++ b/README.md
@@ -367,6 +367,7 @@ The first request after container startup can be slower because CUDA graph captu
 | Very high TTFA | CUDA graph capture failed or fallback path is active | Check logs, reduce `--max-seq-len`, then restart |
 | MP3 output error | MP3 dependencies are missing or ffmpeg is unavailable | Use `wav`/`pcm` or rebuild the image with MP3 support |
 | OpenWebUI has no voices | Client cannot read the voice list | Confirm `/v1/models` and `/v1/audio/voices` are reachable from OpenWebUI |
+| Self-built image crashes in `Qwen3TTSModel.from_pretrained` at startup | Image built from an old Dockerfile that cloned upstream `main` (v0.4.0+, Transformers 5), mixed with `qwen-asr`'s Transformers 4 pin | `git pull` this repo and rebuild with `docker build --no-cache -t faster-qwen3-tts-dgx-spark:latest .` |
 
 ## Hardware requirements
 
@@ -377,6 +378,11 @@ The first request after container startup can be slower because CUDA graph captu
 
 ## Changelog
 
+### v6.10.1 — 2026-09-21
+**Fix: Fresh `docker build` Crashes on Model Load**
+- **Root Cause:** The Dockerfile cloned upstream `faster-qwen3-tts` from `main`. Upstream v0.4.0 (2026-08-25) moved to Transformers 5 (`qwen-tts-hf`), but `qwen-asr` pins `transformers==4.57.6` and downgraded it in the next build step, so `Qwen3TTSModel.from_pretrained` failed on startup. Images built before that date were unaffected.
+- **Fix:** Upstream is now pinned to commit `7cdef7e` (v0.2.6, the version in the released images), with `qwen-tts==0.1.1` and `qwen-asr==0.0.6`. Override with `--build-arg FASTER_QWEN3_TTS_REF=<sha|tag|branch>`.
+
 ### v6.10 — 2026-08-18
 **Fix: Long Text No Longer Truncated Mid-Sentence**
 - **Root Cause:** `/v1/audio/speech` sent the entire request text as one generate call, capped at `--max-seq-len` codec tokens. Text long enough to need more audio than that cap allowed got cut off wherever generation happened to be — mid-sentence, mid-word — with no error surfaced to the client.