Troubleshooting¶

Sometimes, an installation or upgrade will not go as planned. This page details some ways in which to troubleshoot what's happened.

As a general troubleshooting rule, output from the following commands will be helpful:

./manage_server logs will get you logs from the currently running instance of the Enterprise Server
journalctl -xu docker.service on Linux hosts will get you logs from Docker itself (which may be required if Docker itself is failing, rather than the Enterprise Server)

Reset the Enterprise Server Installation¶

If, for any reason, you want to "reset" your entire Enterprise installation and completely start over, you'll need to do the following:

# Optional: Back up your existing data
./manage_server backup

# Stop the Enterprise server
./manage_server stop

# Remove the Docker volumes
# WARNING: THIS WILL IRREVERSIBLY DELETE ALL OF YOUR DATA
./manage_server delete

# Re-install the Enterprise server
./manage_server install

# Optional: Start the server and restore from backup
./manage_server start --detach
./manage_server restore

Unable to Start or Stop the Enterprise Server¶

There are a few common causes of this, detailed in sub-sections below.

Running as Root¶

At the moment, if you are deploying with our included database container, you cannot run as the root user. There is a limitation of the upstream default PostgreSQL container and how we perform our deployment that we have not yet been able to address or work around that prevents this.

Generally speaking, we would prefer customers to run as a non-privileged user anyway, but we do understand there may be a desire to do this. Using an external PostgreSQL service should be a way to work around this for the time being while we work on a resolution.

Trying to run as root will generally manifest in the database container simply not starting and errors in the backend container like this:

binja_enterprise_backend  | Health check attempt 1 failed, retrying in 5 seconds...
binja_enterprise_backend  | database:5432 - no response

Forgetting Swarm Options¶

If you are deploying with Docker Swarm, remember that you currently need the --swarm flag on both the start and stop commands, or manage_server will default to using Docker Compose. If you have specified a non-default stack name, please also remember to use --swarm=<STACK_NAME> as well.

Issues With Overrides¶

If you see the error version mismatched between two composefiles, remove the version: line from your override file. This has been deprecated for awhile (2021), but has only recently (2025) begun causing warnings and errors on newer versions of Docker.

Additionally, if you've made any modifications to the service definition file in the override file, you might want to check the output of a Docker command like docker stack ps binaryninja_enterprise --no-trunc to see if the containers are failing to start for any reason that's been identified by Docker itself.

Network Errors When Starting the Enterprise Server¶

If you are seeing a large number of errors in the log when starting the Enterprise server that say things like "Host is unreachable", this generally points to a host networking issue.

If you are on Red Hat, nftables is the likely culprit as it is known to interfere with docker-compose routes and prevent inter-container networking. The easiest way to fix this is to edit the file /etc/firewalld/firewalld.conf and change the line that says FirewallBackend=nftables to FirewallBackend=iptables. This will switch your system to using iptables as your default firewall instead of nftables. After you do a sudo systemctl restart firewalld.service, the server should be back to working correctly.

Other causes for this problem are more generally related to firewall rules on the local system and/or a misconfiguration of your Docker networking.

Single Sign-On (SSO) Doesn't Work¶

Please see the troubleshooting section listed under your chosen SSO source on this page.

Changing the Volume Location Won't Work¶

If you are trying to change the volume location of an existing install, this may fail and result in the old volume location being used. The reason is that the old Docker volume location will be kept. You will need to use docker volume ls and docker volume inspect <volume name> to identify the volume in question and delete it with docker volume rm <volume name>. Then, when you bring the server up again, it will use the updated value from the service definition file.

Warning

You should always make a backup of your data before messing with any volume locations. Running docker volume rm on any volume will result in permanent data loss from that volume. Please proceed with caution!

Cannot Download Client Executables¶

If, when you download the client executables, you get a 200 response and a 0 byte file, your underlying storage likely has a sector size larger than 4096 bytes. A way to confirm this is to look at the proxy container's logs for an error message that state failed (22: Invalid argument) while sending response to client.

To fix this, you will either need to migrate your server to a storage volume that has a smaller sector size or contact support and we'll help troubleshoot further. This will require changes to the proxy container

Client SSO and Chat Not Working¶

If the Enterprise Server is behind a proxy, ensure that websocket traffic is being forwarded. To do this in Nginx, set the following configuration variables:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";