Troubleshooting

Fix common errors of the Python and TypeScript clients: install problems, version warnings, connection errors, and rejected writes.

Find the error or the symptom that you see, then follow the fix.

pip installs an old synnax version

With a version pin, pip fails with this error instead:

ERROR: Ignored the following versions that require a different python version: 0.33.0 Requires-Python <4.0,>=3.12; ...
ERROR: Could not find a version that satisfies the requirement synnax==0.58.*

Cause

The Python client needs Python 3.12 or later. On an older Python, pip install synnax installs an old release with no error. To see the version that pip installed, run pip show synnax.

Fix

1. Install Python 3.12 or later from python.org or with the package manager of your operating system.

2. Install the client in a virtual environment of the new Python:

   python3.12 -m venv .venv
   source .venv/bin/activate
   pip install synnax

externally-managed-environment

error: externally-managed-environment

Cause

Your operating system manages this Python, so pip does not install packages into it.

Fix

Install the client in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install synnax

sy: command not found

Cause

The shell cannot find the sy command that the Python client installs.

Fix

• The client is in a virtual environment -> activate the environment, or run the command through your environment manager, such as uv run sy login or poetry run sy login.
• The pip that you used is for a different Python -> check with pip --version. Then install with the Python that you use: python3.12 -m pip install synnax.
• The scripts folder of Python is not on your PATH -> pip prints a warning with the folder when it installs the client. Add that folder to your PATH.

Promise.withResolvers is not a function

TypeError: Promise.withResolvers is not a function

ReferenceError: WebSocket is not defined

Cause

The TypeScript client needs Node.js 22 or later. On an older Node.js, connect does not return, and reads, writes, and streamers throw these errors.

Fix

Update Node.js to version 22 or later from nodejs.org. To see your version, run node --version.

Synnax is not a constructor

SyntaxError: The requested module '@synnaxlabs/client' does not provide an export named 'default'

TypeError: Synnax is not a constructor

Error [ERR_REQUIRE_ESM]: require() of ES Module

Cause

The TypeScript client is an ES module with no default export.

Fix

Import Synnax by name with import, not require:

import { Synnax } from "@synnaxlabs/client";

Old Core version

The Synnax Core version 0.57.0 is too old for client version 0.58.1. This may cause compatibility issues. We recommend updating the Core. For more information, see https://docs.synnaxlabs.com/reference/client/troubleshooting#old-core-version

The Synnax Core version 0.57.0 is too old for client version 0.58.1.
  This may cause compatibility issues. We recommend updating the Core. For more information, see
  https://docs.synnaxlabs.com/reference/client/troubleshooting#old-core-version

Cause

The major and minor version of the client is newer than the Core.

Fix

Upgrade the Core, or install the client version that matches the Core:

Python

TypeScript

Enterprise

pip install "synnax==0.57.*"

Old client version

The Synnax Core version 0.58.1 is too new for client version 0.57.0. This may cause compatibility issues. We recommend updating the client. For more information, see https://docs.synnaxlabs.com/reference/client/troubleshooting#old-client-version

The Synnax Core version 0.58.1 is too new for client version 0.57.0.
  This may cause compatibility issues. We recommend updating the client. For more information, see
  https://docs.synnaxlabs.com/reference/client/troubleshooting#old-client-version

Cause

The client is older than the Core.

Fix

Install the client version that matches the Core:

Python

TypeScript

Enterprise

pip install "synnax==0.58.*"

Measured excessive clock skew

Measured excessive clock skew between this host and the Synnax Core. This host is ahead of the Synnax Core by approximately 2s.

Cause

The clocks of your computer and the Core differ by more than one second. Timestamps that your code makes are then wrong by the same amount.

Fix

Synchronize both clocks with a time server, for example with NTP.

Cannot reach the Core

Failed to reach cluster at core.example.com:9090

Cannot reach Core at core.example.com:9090

Cause

One of these:

• The Core does not run, or the host or the port is wrong.
• A firewall blocks the port.
• secure does not match the Core.

Fix

1. Check that the Core runs, and that the host and the port are correct.
2. Check that no firewall blocks the port.
3. Set secure to true when the Core serves TLS, and to false when it does not.

Invalid credentials

invalid credentials: auth error

Cause

The username or password is wrong.

Fix

Give the correct username and password. To change a saved Python login, run sy login again.

No connection parameters were given

ValidationError: No connection parameters were given and none are saved. Open Synnax Desktop, log in with `sy login`, or give a host and a port.

Cause

You created a Python client with no arguments. There is no saved login, and Synnax Desktop has not run on this computer.

Fix

Open Synnax Desktop, run sy login, or give the connection values to sy.Synnax. See Connect to a Core.

Synnax Desktop is not running

Synnax Desktop is not running. Open it and try again. To connect to another Core, give a host and a port.

Cause

You created a Python client with no arguments, and it found the Core of Synnax Desktop. Synnax Desktop is closed, or its Core has not started.

Fix

Open Synnax Desktop and wait until the workspace shows, then run the script again.

Channel not found

NotFoundError: Channel matching 'tank_pressure' not found.

channel not found matching "tank_pressure"

Could not find channels: ["tank_pressure"]

Cause

No channel has this name or key. Channel names are case sensitive.

Fix

Check the spelling. To see the channels of the Core, see Find channels.

Write overlaps with existing data

cannot open writer because there is already data in the writer's time range

write overlaps with existing data in database

Cause

A channel already has samples in the time range of the write. The first error comes when the writer opens, and the second when it commits.

Fix

Write to a time range that has no samples, or delete the samples first.

Frame must have the same length for all series

frame must have the same length for all series

Cause

In one write, an index channel and its data channels need the same number of samples. The client raises a ValidationError.

Fix

Give the index channel and each of its data channels the same number of samples. See Rule 1.

Received no data for index channel

received no data for index channel [time]<1> that must be provided when writing to related data channels [[temperature]<2>]

Cause

The write holds samples for a data channel, but not for its index channel.

Fix

Add the timestamps to the write, or turn on auto-index. See the rules of writes.