Pinch PINCH

Troubleshooting

Common issues

pip install pinch-sdk fails with Python version errors

When installing the SDK, you may see errors like:

ERROR: Ignored the following versions that require a different python version
ERROR: Could not find a version that satisfies the requirement pinch-sdk
ERROR: No matching distribution found for pinch-sdk

The Pinch Python SDK requires Python 3.10 or newer.

If the installation tool is using a Python interpreter below 3.10, all available SDK versions are ignored, and installation fails.

Fix

  1. Check your Python version:

    python3 --version

  2. If the version is below 3.10, install a newer Python version.

    Refer to the official Python installation guide for your operating system:

    https://www.python.org/downloads/

  3. After installing Python 3.10+, retry the SDK installation using your preferred tool:

    python3 -m pip install pinch-sdk

Authentication failed (PinchAuthError)

Running the SDK raises an authentication error:

pinch.errors.PinchAuthError: Authentication failed. Check your PINCH_API_KEY in the Pinch Portal.

The SDK could not authenticate with the Pinch service. This usually happens when:

  • PINCH_API_KEY is missing from the environment
  • the API key is invalid or revoked
  • the API key belongs to a different account or environment
  • credits are not enabled for the account

This error is returned by the Pinch service during session creation.

Fix

  1. Set the API key in your environment:

    export PINCH_API_KEY=pk_your_key_here

    or create a .env file in your project directory:

    PINCH_API_KEY=pk_your_key_here

    Keep your API key private. Do not commit it to GitHub or include it in client-side code.

  2. Confirm the API key is valid in the Pinch Portal:

    • log in to the Portal
    • check that the key exists and is active

  3. If you recently changed keys, restart your terminal or shell to ensure the updated value is picked up.

  4. Re-run the script using the same Python interpreter that has the SDK installed:

    python3 examples/translate.py

Unsupported source or target language (PinchValidationError)

Running the SDK fails with a validation error similar to:

pinch.errors.PinchValidationError: Unsupported source language: en-U.
Supported languages: en-US, en-GB, es-ES, …

An invalid or incomplete language code was passed to the SDK.

Pinch requires full language codes (for example en-US, es-ES, fr-FR), not partial or shorthand values.

In this case, en-U is not a valid language code, so the SDK rejects the request during session creation.

Fix

  1. Verify the language code you are using for source_language and target_language.
  2. Update your code to use a supported language code (see Supported languages >).
  3. Re-run the script after making the change.

Notes

  • Language codes are case-sensitive and must match the supported list exactly.
  • The error message includes the full list of supported language codes for reference.

No translated audio received (PinchProtocolError)

Running the file translation example fails with:

pinch.errors.PinchProtocolError: No translated audio was received; cannot create an output audio file.

The translation request completed, but no translated audio frames were returned by the service.

This can happen when:

  • the input audio file contains little or no audible speech
  • the audio is silent, extremely quiet, or mostly background noise
  • the spoken language does not match source_language
  • the audio duration is very short (for example, less than a second)
  • the language pair is unsupported for audio output
  • audio output is disabled (explicitly or implicitly)

In this situation, the SDK cannot create an output WAV file because there is no audio data to write.

Fix

Work through the checklist below:

  1. Verify the input audio contains clear speech

    • Confirm the WAV file actually contains audible speech
    • Avoid silent or near-silent clips
    • Speak clearly and at normal volume
    • Try a clip that is at least 5 seconds long

  2. Verify the source language

    • Ensure source_language matches the language spoken in the audio.
    source_language="en-US"
    • If the audio is in another language, update the parameter accordingly.

  3. Confirm audio output is enabled

    • If you passed audio_output_enabled=False, no audio will be returned.

    • Ensure audio output is enabled (default behavior):

    await client.translate_file(
    input_wav_path="input.wav",
    output_wav_path="output.wav",
    transcript_path="transcript.txt",
    audio_output_enabled=True,
)

Invalid WAV file format (wave.Error)

Running the file translation example fails with an error similar to:

wave.Error: file does not start with RIFF id

The input file is not a valid WAV file, or is a WAV file with an unsupported encoding.

Pinch file-based translation expects:

  • WAV container
  • 16-bit PCM encoding
  • Supported sample rates: 16 kHz or 48 kHz

This error typically occurs when:

  • the file is not actually a WAV file (for example, MP3 renamed to .wav)
  • the WAV file uses a compressed codec
  • the file is corrupted or partially written
  • the file header does not follow the RIFF specification

Fix

Verify the file type:

file input.wav

It should report something like:

RIFF (little-endian) data, WAVE audio

If unsure, re-encode the file explicitly:

ffmpeg -i input.wav -ac 1 -ar 16000 -sample_fmt s16 fixed.wav

Retry with the converted file:

input_wav_path="fixed.wav"

Facing more issues or need more help?

Email us at support@startpinch.com.

We’ll help you debug, and we’ll use what we learn to improve the docs.