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

```plaintext
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 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](https://www.python.org/downloads/) or with the package manager of your operating system.

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

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

## externally-managed-environment

```plaintext
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:

  ```bash
  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

```plaintext
TypeError: Promise.withResolvers is not a function
```

```plaintext
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](https://nodejs.org/). To see your version, run `node --version`.

## Synnax is not a constructor

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

```plaintext
TypeError: Synnax is not a constructor
```

```plaintext
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`:

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

## Old Core version

**Python**

```plaintext
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-version
```

**TypeScript**

```plaintext
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-version
```

* Cause

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

* Fix

  [Upgrade the Core](https://docs.synnaxlabs.com/reference/enterprise/upgrade), or install the client version that matches the Core:

  **Python**

  ```bash
  pip install "synnax==0.60.*"
  ```

  **TypeScript**

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

## Old client version

**Python**

```plaintext
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-version
```

**TypeScript**

```plaintext
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-version
```

* Cause

  The client is older than the Core.

* Fix

  Install the client version that matches the Core:

  **Python**

  ```bash
  pip install "synnax==0.61.*"
  ```

  **TypeScript**

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

## Synnax Desktop runs Core version

```plaintext
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](https://docs.synnaxlabs.com/reference/client/connect#connect-to-synnax-desktop), and the major and minor version of the client do not match its Core.

* Fix

  Run the `pip install` command that the warning gives. When the client is newer, you can update Synnax Desktop instead.

## Measured excessive clock skew

```plaintext
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**

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

**TypeScript**

```plaintext
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

```plaintext
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](https://docs.synnaxlabs.com/reference/client/connect#connect-with-an-api-key). To change a saved Python login, run `sy login` again.

## Session ended

```plaintext
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](https://docs.synnaxlabs.com/reference/client/connect#connect-to-synnax-desktop).

## Access denied

```plaintext
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](https://docs.synnaxlabs.com/reference/enterprise/users).

## No connection parameters were given

```plaintext
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](https://docs.synnaxlabs.com/reference/client/connect).

## Synnax Desktop is not running

```plaintext
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](https://docs.synnaxlabs.com/reference/client/connect#connect-to-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**

```plaintext
NotFoundError: Found no channel where name = "tank_pressure"
```

```plaintext
NotFoundError: channels not found matching ["tank_pressure"]
```

**TypeScript**

```plaintext
Found no channel where name = "tank_pressure"
```

```plaintext
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](https://docs.synnaxlabs.com/reference/channels/find).

## Write overlaps with existing data

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

```plaintext
cannot start writer because there is already data in the writer's time range
```

```plaintext
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 a writer with a `start` opens. The second comes at the first write of a writer with no `start`. The third comes when the writer commits.

* Fix

  Write to a time range that has no samples, or [delete the samples](https://docs.synnaxlabs.com/reference/client/delete-data) first.

## Frame must have the same length for all series

```plaintext
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](https://docs.synnaxlabs.com/reference/client/write-data#rule-1).

## Received no data for index channel

```plaintext
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](https://docs.synnaxlabs.com/reference/client/write-data#the-rules-of-writes).

## Stream holds more than 268435456 bytes of unread messages

```plaintext
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](https://docs.synnaxlabs.com/reference/client/stream-data#slow-the-stream).
