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 Serverjournalctl -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";