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.61.*- Cause
The Python client needs Python 3.12 or later. On an older Python,
pip install synnaxinstalls an old release with no error. To see the version that pip installed, runpip show synnax.- Fix
-
Install Python 3.12 or later from python.org or with the package manager of your operating system.
-
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
sycommand 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 loginorpoetry 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 yourPATH.
- The client is in a virtual environment -> activate the environment, or run the
command through your environment manager, such as
Promise.withResolvers is not a function
TypeError: Promise.withResolvers is not a functionReferenceError: WebSocket is not defined- Cause
The TypeScript client needs Node.js 22 or later. On an older Node.js,
connectdoes 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 constructorError [ERR_REQUIRE_ESM]: require() of ES Module- Cause
The TypeScript client is an ES module with no default export.
- Fix
Import
Synnaxby name withimport, notrequire:import { Synnax } from "@synnaxlabs/client";
Old Core version
Python
TypeScript
The Synnax Core version 0.60.0 is too old for client version 0.61.0. This may cause compatibility issues. We recommend updating the Core. For more information, see https://docs.synnaxlabs.com/reference/client/troubleshooting#old-core-versionThe Synnax Core version 0.60.0 is too old for client version 0.61.0.
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
pip install "synnax==0.60.*"npm install @synnaxlabs/client@0.60
Old client version
Python
TypeScript
The Synnax Core version 0.61.0 is too new for client version 0.60.0. This may cause compatibility issues. We recommend updating the client. For more information, see https://docs.synnaxlabs.com/reference/client/troubleshooting#old-client-versionThe Synnax Core version 0.61.0 is too new for client version 0.60.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
pip install "synnax==0.61.*"npm install @synnaxlabs/client@0.61
Synnax Desktop runs Core version
Synnax Desktop runs Core version 0.60.1, which does not match client version 0.61.0. Update Synnax Desktop, or run pip install "synnax~=0.60.0".- Cause
A Python client connected to Synnax Desktop, and the major and minor version of the client do not match its Core.
- Fix
Run the
pip installcommand that the warning gives. When the client is newer, you can update Synnax Desktop instead.
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
Python
TypeScript
Failed to reach cluster at core.example.com:9090Cannot 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.
securedoes not match the Core.
- Fix
- Check that the Core runs, and that the host and the port are correct.
- Check that no firewall blocks the port.
- Set
secureto true when the Core serves TLS, and to false when it does not.
Invalid credentials
invalid credentials: auth error- Cause
The username, password, or API key is wrong, or someone deleted or reset the API key.
- Fix
Give the correct username and password, or a valid API key. See Connect with an API key. To change a saved Python login, run
sy loginagain.
Session ended
session ended: invalid token: auth error- Cause
The session of an open streamer, writer, or iterator ended. Someone reset or deleted the API key, or the session timed out.
- Fix
Open the streamer, writer, or iterator again. The client logs in again by itself. When someone reset the key, give the client the new key. For Synnax Desktop, see Connect to Synnax Desktop.
Access denied
user:7f3c3e2a-0d4e-4b8e-9a1e-2c6f5b9d8e10 cannot delete channel:1048577: access denied: auth error- Cause
The role of the user that the client logs in as does not allow the action on the resource. Each user has one role.
- Fix
Ask an administrator to give your user a role that allows the action. See Users.
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 tosy.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
Python
TypeScript
NotFoundError: Found no channel where name = "tank_pressure"NotFoundError: channels not found matching ["tank_pressure"]Found no channel where name = "tank_pressure"channels not found matching ["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 rangecannot start writer because there is already data in the writer's time rangewrite overlaps with existing data in database- Cause
A channel already has samples in the time range of the write. The first error comes when a writer with a
startopens. The second comes at the first write of a writer with nostart. The third comes when the writer 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.
Stream holds more than 268435456 bytes of unread messages
stream holds more than 268435456 bytes of unread messages- Cause
A TypeScript streamer got frames faster than your code read them. The client keeps unread frames in memory, and closes the streamer when they pass 256 MB.
- Fix
Read frames faster, or send fewer of them. See Slow the stream.