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
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.
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 pythonRed Hat / Amazon Linux:
sudo yum install python3.12.x86_64 python3.12-devel.x86_64 python3.12-pip.noarchUbuntu (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 --versionThe 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.
Download and run the Windows installer from nodejs.org. The installer will automatically add Node.js to your PATH.
Alternatively, if using Windows Subsystem for Linux, follow the Linux instructions instead.
Homebrew is recommended for installing Node.js:
brew install nodeUbuntu / 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 --versionRed Hat / Amazon Linux:
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejsIncorrect Version
Synnax requires Python 3.12+. Check your version:
python --version # or try: python3 --version, python3.12 --versionIf the output shows Python 3.12.x or higher, the version is compatible. If older,
update Python:
Reinstall from python.org - make sure to check “Add Python to PATH”.
See the Installing the Language section above for distribution-specific instructions.
brew upgrade pythonCheck your Node.js version:
node --versionIf you need to update, see the Installing the Language section above.
Command Not Found
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.
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 ~/.zshrcCommon 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 ~/.bashrcIf node --version returns command not found, Node.js isn’t on your PATH.
Reinstall from nodejs.org - the installer automatically adds Node.js to PATH.
# If installed via homebrew
export PATH="/opt/homebrew/bin:$PATH"
# Make permanent
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc# Common location after nodesource install
export PATH="/usr/bin:$PATH"
# Make permanent
echo 'export PATH="/usr/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcSynnax Command Not Found
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 higherIf 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:
| 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/clientimport 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:
pip install synnax==x.x.xnpm install @synnaxlabs/client@x.x.xOld 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:
pip install --upgrade synnaxnpm install @synnaxlabs/client@latest