Troubleshoot Synnax Enterprise

Find why a Synnax Core does not start, why the Console cannot connect, and fix license problems.

Start with the log of the Core, then find the message or symptom below. For problems in other parts of Synnax, see client troubleshooting, hardware troubleshooting, and Synnax Desktop troubleshooting.

Read the log

The Core writes its log to its terminal and to the file set by --log-file-path:

• Terminal or Docker -> the output of synnax start or docker logs synnax.
• systemd -> journalctl -u synnax -a.
• Windows service -> C:\ProgramData\Synnax\logs\synnax.log, or synnax service status for the last errors.
• Other -> ./synnax-logs/synnax.log in the folder where the Core started.

For more detail, start the Core with --verbose.

The Core does not start

When the Core cannot start, it logs Synnax has encountered an error and is shutting down:, then the cause.

node certificate not found

Cause

The Core uses TLS by default and found no certificate in /usr/local/synnax/certs.

Fix

Start the Core with --auto-cert to create a certificate, set --certs-dir to your certificates, or use --insecure for a test Core. See Set up TLS.

serves a certificate that does not cover that host

Cause

The certificate does not cover the --listen host.

Fix

Use a certificate for that host, or change --listen to a name the certificate covers. See Set up TLS.

bind: address already in use

Cause

Another program uses the port. On Windows, the message is “Only one usage of each socket address is normally permitted”.

Fix

Stop that program, or start the Core on a different port in --listen.

Failed to acquire lock on storage directory

Cause

Another Core uses the same data folder.

Fix

Stop the other Core, or start this one with a different --data folder.

permission denied

Cause

The user that runs the Core cannot write a folder it needs: the data folder, the log folder, the certificate folder, or its home folder. A message about $HOME means the user has no home folder.

Fix

Give the user write access, or set --data, --log-file-path, and --certs-dir to folders it can write. See Run the Core as a service.

Synnax requires the storage directory to have at least -rwx—— permissions

Cause

The owner of the data folder cannot read, write, or open it.

Fix

Run chmod u+rwx on the folder.

The disk is full

Cause

The Core does not check free space. When the data disk is full, the Core can stop with “no space left on device”.

Fix

1. Free space on the disk.
2. Start the Core.

The Console cannot connect or log in

The Core shows as Unreachable

Cause

The Console cannot use the Core. Hover over the status to see the reason.

Fix

• Cannot reach Core at -> check that the Core runs, the host and port are correct, and a firewall allows the port. For a Core with TLS, turn on Secure, and install its certificate if it is self-signed.
• No license is active on this Core -> log in, then activate a license.
• The license on this Core has expired -> see expiry.

invalid credentials

Cause

The username or password is wrong.

Fix

For the root user, restart the Core with a new --password. For other users, an Owner deletes the user and registers them again. See Users.

Version mismatch

Cause

The Console and the Core have a different major or minor version.

Fix

Upgrade the older one. See Upgrade the Core.

Clock is ahead of the Core

Cause

The clocks of this computer and the Core differ by more than one second.

Fix

Synchronize both clocks with NTP.

Live updates are unavailable

Cause

The role of the user cannot read the channels that carry live changes.

Fix

An Owner gives the user a role with more permissions. See roles.

License problems

refused the license key passed at startup

Cause

The Core refused the key that you gave with --license-key, --license-file, or SYNNAX_LICENSE_KEY. The log says why: “the license was not issued for this machine”, “invalid license”, “the license on this Core has expired”, or “a Desktop license runs only on a Core that listens on loopback addresses”. An old numeric key logs “numeric license keys are no longer accepted”. The Core starts with the keys that it stored, or without a license.

Fix

Get a new key from the portal, and replace the key file or variable. See Activate a license.

The license term cannot be checked

Cause

The system clock moved back. The log says that the system clock is more than 24 hours behind the last recorded time.

Fix

Fix the clock. The license then applies again.

The license stopped after a hardware change

Cause

The network hardware of the computer changed, so its fingerprint changed. A recreated Docker container without a fixed --mac-address has the same problem. The log says skipping a stored license key that does not fit this Core.

Fix

Activate the license again with the new fingerprint. See Activate a license.

using more channels than allowed by the license

Cause

The Core has as many channels as the license allows. Virtual channels do not count. See channel limit.

Fix

To create more channels, replace the license with one that allows more. See renew or replace a license.