# Troubleshooting

> Solve common issues when working with the Synnax client.

This page covers common issues users encounter when working with the Synnax client libraries.

## Installing the language

**Python**

Synnax doesn’t enforce a specific way to work with Python, although our development team recommends using the latest version of the official [Python installer](https://www.python.org/downloads/).

**Linux**

**Red Hat / Amazon Linux:**

```bash
sudo yum install python3.12.x86_64 python3.12-devel.x86_64 python3.12-pip.noarch
```

**Ubuntu** (24.04 has Python 3.12 pre-installed; for older versions use `deadsnakes`):

```bash
# Update package index and install dependencies
sudo apt update
sudo apt install build-essential software-properties-common -y

# Add deadsnakes PPA and install Python 3.12
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 -y

# Verify installation
python3.12 --version
```

**Windows**

Make sure to check the box that says “Add Python to PATH” during the installation process. This will ensure that the `python` command is available in your terminal.

Alternatively, if you plan to use Synnax inside [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), follow the instructions for Linux instead.

**macOS**

On macOS, [homebrew](https://brew.sh/) is recommended for installing Python. Homebrew makes configuring newer Python versions much easier than using the installer.

```bash
brew install python
```

**TypeScript**

The latest version of Node.js from the [official Node.js website](https://nodejs.org/) is recommended.

> After installing Node.js, you can install the Synnax client with `npm install @synnaxlabs/client`.

**Linux**

**Ubuntu / Debian:**

```bash
# Install Node.js 24.x
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

# Verify installation
node --version
npm --version
```

**Red Hat / Amazon Linux:**

```bash
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejs
```

**Windows**

Download and run the Windows installer from [nodejs.org](https://nodejs.org/). The installer will automatically add Node.js to your PATH.

Alternatively, if using [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10), follow the Linux instructions instead.

**macOS**

[Homebrew](https://brew.sh/) is recommended for installing Node.js:

```bash
brew install node
```

## Incorrect version

**Python**

Synnax requires Python 3.12+. Check your version:

```bash
python --version # or try: python3 --version, python3.12 --version
```

If the output shows `Python 3.12.x` or higher, the version is compatible. If older, update Python:

**Linux**

See the [Installing the Language](https://docs.synnaxlabs.com/reference/client/troubleshooting#installing-the-language) section above for distribution-specific instructions.

**Windows**

Reinstall from [python.org](https://www.python.org/downloads/) - make sure to check “Add Python to PATH”.

**macOS**

```bash
brew upgrade python
```

**TypeScript**

Check your Node.js version:

```bash
node --version
```

If you need to update, see the [Installing the Language](https://docs.synnaxlabs.com/reference/client/troubleshooting#installing-the-language) section above.

## Command not found

**Python**

If `python --version` returns `command not found`, the executable isn’t on your PATH.

> If multiple Python versions are installed, an older version may shadow the newer one in your PATH. Check your PATH order and remove or reorder conflicting entries.

**Linux**

**Common install location:** `/usr/bin/python3.12`

```bash
# Add to PATH temporarily
export PATH="/usr/bin:$PATH"

# Or permanently (add to ~/.bashrc)
echo 'export PATH="/usr/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**Windows**

**Common install locations:**

* Official installer: `C:\Users\{username}\AppData\Local\Programs\Python312`
* Anaconda: `C:\Users\{username}\Anaconda3`

**To fix:** Search “environment variables” in Start Menu → Edit system environment variables → Environment Variables → Edit `Path` → Add your Python directory → Log out and back in.

**macOS**

**Common install location:** `/opt/homebrew/bin/python3`

```bash
# Add to PATH temporarily
export PATH="/opt/homebrew/bin:$PATH"

# Or permanently (add to ~/.zshrc)
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**TypeScript**

If `node --version` returns `command not found`, Node.js isn’t on your PATH.

**Linux**

```bash
# Common location after nodesource install
export PATH="/usr/bin:$PATH"

# Make permanent
echo 'export PATH="/usr/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**Windows**

Reinstall from [nodejs.org](https://nodejs.org/) - the installer automatically adds Node.js to PATH.

**macOS**

```bash
# If installed via homebrew
export PATH="/opt/homebrew/bin:$PATH"

# Make permanent
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

## Synnax command not found

**Python**

If `synnax` returns `command not found` after installing via pip:

**1. Check pip is using the correct Python version:**

```bash
pip --version # Should show (python 3.12) or higher
```

If it shows an older version, your PATH may point to the wrong pip. See [Command not found](https://docs.synnaxlabs.com/reference/client/troubleshooting#command-not-found) for PATH troubleshooting.

**2. If using a virtual environment, run commands within it.** Use the command for your environment manager:

| Tool   | Command                                                     |
| ------ | ----------------------------------------------------------- |
| uv     | `uv run sy --help`                                          |
| poetry | `poetry run sy --help` (or `poetry shell` then `sy --help`) |
| venv   | `source venv/bin/activate` then `sy --help`                 |
| conda  | `conda activate myenv` then `sy --help`                     |

**TypeScript**

The TypeScript client is a library, not a CLI tool. Install it via npm and import it directly into your code:

```bash
npm install @synnaxlabs/client
```

```typescript
import Synnax from "@synnaxlabs/client";
```

## Old Core version

```plaintext
Synnax Core version is too old for client version x.x.x. This may cause compatibility
issues. We recommend updating the Core.
```

Your client is newer than the Synnax Core you’re connecting to. Either [upgrade Synnax Core](https://docs.synnaxlabs.com/reference/core/installation) or downgrade the client:

**Python**

```bash
pip install synnax==x.x.x
```

**TypeScript**

```bash
npm install @synnaxlabs/client@x.x.x
```

## Old client version

```plaintext
Synnax Core version is too new for client version x.x.x. This may cause
compatibility issues. We recommend updating the client.
```

Your client is older than the Synnax Core you’re connecting to. Update the client:

**Python**

```bash
pip install --upgrade synnax
```

**TypeScript**

```bash
npm install @synnaxlabs/client@latest
```