ATH-MaaS/Pixelle-Video · error · HTTPException

str(e)

Error message

str(e)

What it means

A 500 HTTPException raised in tts_synthesize (api/routers/tts.py:93) by its blanket `except Exception` handler. Any failure during text-to-speech synthesis — engine errors, file writes, invalid input reaching the engine — is caught, logged as 'TTS synthesis error', and re-raised with detail=str(e), so the client sees the raw internal exception text with status 500.

Source

Thrown at api/routers/tts.py:93

        # Legacy voice_id support (deprecated)
        if request.voice_id and not request.workflow:
            logger.warning("voice_id parameter is deprecated, please use workflow instead")
            tts_params["voice"] = request.voice_id
        
        # Call TTS service
        audio_path = await pixelle_video.tts(**tts_params)
        
        # Get audio duration
        duration = get_audio_duration(audio_path)
        
        return TTSSynthesizeResponse(
            audio_path=audio_path,
            duration=duration
        )
        
    except Exception as e:
        logger.error(f"TTS synthesis error: {e}")
        raise HTTPException(status_code=500, detail=str(e))

View on GitHub (pinned to 848b054e4f)

Solutions

  1. Read the 'TTS synthesis error: ...' server log to identify the underlying exception.
  2. Verify the TTS engine/model is installed and loadable on the server (run a minimal synthesis in a shell/repl).
  3. Validate the request text client-side: non-empty, within length limits, characters the engine supports, supported language.
  4. Check that the audio output directory exists and is writable by the server process, and that disk space is sufficient.
  5. Replace detail=str(e) with a generic client message and log the traceback server-side; return 400 instead of 500 for invalid input.

Example fix

# before
except Exception as e:
    logger.error(f"TTS synthesis error: {e}")
    raise HTTPException(status_code=500, detail=str(e))
# after
except ValueError as e:  # bad input
    raise HTTPException(status_code=400, detail=f"Invalid TTS input: {e}")
except Exception:
    logger.exception("TTS synthesis error")
    raise HTTPException(status_code=500, detail="TTS synthesis failed")
Defensive patterns

Strategy: validation

Validate before calling

# caller-side pre-check before calling the TTS API
text = request.text.strip()
if not text:
    raise ValueError("text is empty")
if len(text) > MAX_TTS_LENGTH:
    raise ValueError(f"text too long: {len(text)} > {MAX_TTS_LENGTH}")
if not is_supported_language(request.language):
    raise ValueError(f"unsupported language: {request.language}")

Type guard

def is_valid_tts_request(req) -> bool:
    return (
        isinstance(getattr(req, 'text', None), str)
        and 0 < len(req.text.strip()) <= MAX_TTS_LENGTH
    )

Try / catch

try {
  const res = await fetch('/tts/synthesize', { method: 'POST', body: payload });
  if (res.status === 500) {
    // engine/output failure server-side; check server logs for 'TTS synthesis error'
    return fallbackToAlternateVoiceEngine(payload);
  }
  if (res.status === 400) showUserInputError(await res.json());
  return await res.blob();
} catch (err) {
  handleSynthesisFailure(err);
}

Prevention

When it happens

Trigger: TTS engine/model not installed or fails to load; empty/oversized/unsupported-language text passed to the synthesizer; disk full or unwritable output directory when saving audio_path; downstream synthesis call raising (codec/timeout/license error).

Common situations: Server deployed without the TTS model files or missing system dependencies (e.g. espeak for some engines); text containing characters the engine can't handle; audio output directory permissions wrong after a container change; long text exceeding engine limits causing a timeout; str(e) empty for exceptions that carry no message.

Related errors

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/af36772007b75bb6. Report an issue: GitHub.