---
title: "Troubleshooting"
section: "Resources"
order: 0
---

## Common issues

### `pip install pinch-sdk` fails with Python version errors

When installing the SDK, you may see errors like:

```text
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:

   <div class="docs-tabbed" data-docs-tabbed>
     <div class="docs-tabbed__bar">
       <div class="docs-tabbed__tabs" role="tablist" aria-label="Check Python version">
         <button class="docs-tabbed__tab is-active" type="button" role="tab" aria-selected="true" data-tab="mac">macOS</button>
         <button class="docs-tabbed__tab" type="button" role="tab" aria-selected="false" data-tab="win">Windows</button>
       </div>
       <button class="docs-tabbed__copy" type="button" aria-label="Copy commands" data-docs-tabbed-copy></button>
     </div>
     <div class="docs-tabbed__panel is-active" role="tabpanel" data-panel="mac">
       <pre><code class="language-bash">python3 --version</code></pre>
     </div>
     <div class="docs-tabbed__panel" role="tabpanel" hidden data-panel="win">
       <pre><code class="language-powershell">python --version</code></pre>
     </div>
   </div>

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/](https://www.python.org/downloads/)

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

   <div class="docs-tabbed" data-docs-tabbed>
     <div class="docs-tabbed__bar">
       <div class="docs-tabbed__tabs" role="tablist" aria-label="Install Pinch SDK">
         <button class="docs-tabbed__tab is-active" type="button" role="tab" aria-selected="true" data-tab="mac">macOS</button>
         <button class="docs-tabbed__tab" type="button" role="tab" aria-selected="false" data-tab="win">Windows</button>
       </div>
       <button class="docs-tabbed__copy" type="button" aria-label="Copy commands" data-docs-tabbed-copy></button>
     </div>
     <div class="docs-tabbed__panel is-active" role="tabpanel" data-panel="mac">
       <pre><code class="language-bash">python3 -m pip install pinch-sdk</code></pre>
     </div>
     <div class="docs-tabbed__panel" role="tabpanel" hidden data-panel="win">
       <pre><code class="language-powershell">python -m pip install pinch-sdk</code></pre>
     </div>
   </div>

---

### Authentication failed (`PinchAuthError`)

Running the SDK raises an authentication error:

```text
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:

   <div class="docs-tabbed" data-docs-tabbed>
     <div class="docs-tabbed__bar">
       <div class="docs-tabbed__tabs" role="tablist" aria-label="Set PINCH_API_KEY">
         <button class="docs-tabbed__tab is-active" type="button" role="tab" aria-selected="true" data-tab="mac">macOS</button>
         <button class="docs-tabbed__tab" type="button" role="tab" aria-selected="false" data-tab="win">Windows</button>
       </div>
       <button class="docs-tabbed__copy" type="button" aria-label="Copy commands" data-docs-tabbed-copy></button>
     </div>
     <div class="docs-tabbed__panel is-active" role="tabpanel" data-panel="mac">
       <pre><code class="language-bash">export PINCH_API_KEY=pk_your_key_here</code></pre>
     </div>
     <div class="docs-tabbed__panel" role="tabpanel" hidden data-panel="win">
       <pre><code class="language-powershell">$env:PINCH_API_KEY="pk_your_key_here"</code></pre>
     </div>
   </div>

   or create a `.env` file in your project directory:

   ```text
   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:

   <div class="docs-tabbed" data-docs-tabbed>
     <div class="docs-tabbed__bar">
       <div class="docs-tabbed__tabs" role="tablist" aria-label="Run example script">
         <button class="docs-tabbed__tab is-active" type="button" role="tab" aria-selected="true" data-tab="mac">macOS</button>
         <button class="docs-tabbed__tab" type="button" role="tab" aria-selected="false" data-tab="win">Windows</button>
       </div>
       <button class="docs-tabbed__copy" type="button" aria-label="Copy commands" data-docs-tabbed-copy></button>
     </div>
     <div class="docs-tabbed__panel is-active" role="tabpanel" data-panel="mac">
       <pre><code class="language-bash">python3 examples/translate.py</code></pre>
     </div>
     <div class="docs-tabbed__panel" role="tabpanel" hidden data-panel="win">
       <pre><code class="language-powershell">python examples/translate.py</code></pre>
     </div>
   </div>

---

### Unsupported source or target language (`PinchValidationError`)

Running the SDK fails with a validation error similar to:

```text
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 >](/docs/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:

```text
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.

   ```python
   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):

   ```python
   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:

```text
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:

```bash
file input.wav
```

It should report something like:

```text
RIFF (little-endian) data, WAVE audio
```

If unsure, re-encode the file explicitly:

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

Retry with the converted file:

```python
input_wav_path="fixed.wav"
```

---

### Facing more issues or need more help?

Email us at [support@startpinch.com](mailto:support@startpinch.com).

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