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

TypeScript

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.

Linux

Windows

macOS

Red Hat / Amazon Linux:

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

# 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

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, follow the instructions for Linux instead.

On macOS, homebrew is recommended for installing Python. Homebrew makes configuring newer Python versions much easier than using the installer.

brew install python

The latest version of Node.js from the official Node.js website is recommended.

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

Linux

Windows

macOS

Ubuntu / Debian:

# 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:

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

Homebrew is recommended for installing Node.js:

brew install node

Incorrect version

Python

TypeScript

Synnax requires Python 3.12+. Check your version:

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

Windows

macOS

See the Installing the Language section above for distribution-specific instructions.

brew upgrade python

Check your Node.js version:

node --version

If you need to update, see the Installing the Language section above.

Command not found

Python

TypeScript

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

Windows

macOS

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

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

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

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.

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

# 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

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

Linux

Windows

macOS

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

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

# 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

TypeScript

If synnax returns command not found after installing via pip:

1. Check pip is using the correct Python version:

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 for PATH troubleshooting.

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

Table

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`

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

npm install @synnaxlabs/client

import Synnax from "@synnaxlabs/client";

Old Core version

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 or downgrade the client:

Python

TypeScript

pip install synnax==x.x.x

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

Old client version

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

TypeScript

pip install --upgrade synnax

npm install @synnaxlabs/client@latest

Examples