---
title: "Troubleshooting Polarity Server v5: Admin Guide"
slug: "polarity-troubleshooting-v5"
description: "Resolve common issues with Polarity Server v5 deployment and administration. Find error diagnostics, Docker troubleshooting steps, and server configuration fixes to restore annotation platform functionality."
updated: 2026-02-06T22:49:19Z
published: 2026-02-06T22:49:19Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.threatconnect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Polarity v5

*This page is for overall troubleshooting of Polarity Server v5.*

## Polarity Server “Functions Check”

Use this procedure to ensure major functions of a Polarity Server are operational.

1. **Navigate to the Polarity Server’s user interface.**
  1. ***What you should see:***
    1. The Polarity Server login screen or the Polarity Server search interface (if already logged in).
  2. ***What this tells you:***
    1. The Polarity Server is accessible over the network.
    2. The Polarity Server containers are running.
2. **Log into the Polarity Server’s user interface.**
  1. ***What you should see:***
    1. The Polarity Server logs you into the Search or Configuration interface.
  2. ***What this tells you:***
    1. The Polarity Server database is connected and operational.
3. **Install or Update an integration.**
  1. ***What you should see:***
    1. A successful install or update of the selected integration.
  2. ***What this tells you:***
    1. The Polarity Integration Store is accessible from your Polarity Server.
    2. The Polarity Server’s installed certificates match the URL you are using to access the Polarity Server’s user interface.
4. **Conduct a search operation using an integration that requires external access.**
  1. ***What you should see:***
    1. Either search results from the integration or nothing (ie. no error).
  2. ***What this tells you:***
    1. The infrastructure connecting the Polarity Server to the external resource is configured properly.

> [!WARNING]
> Note
> 
> If any of these steps fail, please contact **your Polarity Customer Success Team** or **Support@Polarity.IO** for assistance.

## General Troubleshooting Tips

### Check if containers are running

To check if the containers are running run the following command and check for the up time of the containers:

```shell
cd /app
./health_check.sh
```

If the up time is only a few seconds then the container is failing to start up.

### Checking logs of the containers

Polarity's logs are now stored within the Docker containers and can be tailed or grepped with the following command:

#### Polarity Platform Container

```shell
docker logs polarity_platform 
docker logs polarity_platform |& grep -i "your search term"
```

#### Polarity Web Container

```shell
docker logs polarity_web 
docker logs polarity_web |& grep -i "your search term"
```

---

## Polarity Platform doesn't start

This section will walk through what to do if the `polarity_platform` container is not starting or is constantly restarting:

The first thing to do is to check the `/app/.env` file to ensure the hostname is set correctly:

1. Open the `/app/.env` file for editing.
2. Check that the following lines are set to the correct FQDN for your server:

```plaintext
POLARITY_HOSTNAME={{Correct Hostname}}
POLARITY_WEB_HOSTNAME={{Correct Hostname}}
```

If the hostname is set correctly, check for errors in the logs of the `polarity_platform` container. The error will typically show at the end of the logs.

```shell
docker logs polarity_platform
```

If there is an error not able to read license key then please check if the `server.crt` and `polarity.pem` files exist in the correct locations.

If the errors seems unknown, please reach out to support@polarity.io

---

## Polarity Web doesn't start

This section will walk through what to do if the `polarity_web` container is not starting or is just constantly restarting:

The first thing to do is to check the `/app/.env` file to ensure the hostname is set correctly:

1. Open the `/app/.env` file for editing.
2. Check that the following lines are set to the correct FQDN for your server:

```plaintext
POLARITY_HOSTNAME={{Correct Hostname}}
POLARITY_WEB_HOSTNAME={{Correct Hostname}}
```

If the hostnames are all set, check the errors in the logs for the `polarity_web` container. The error will typically show at the end of the logs.

```shell
docker logs polarity_web
```

If you are seeing an error like "Private Key does not match Public Key." this typically indicates an issue with the SSL certificates causing the web container to fail to start.

See the following page for more troubleshooting details:

- [Configure the Server SSL Certificates](/v1/docs/configure-the-server-ssl-certificates)

As always, please reach out to support@polarity.io for support.

---

## Integration Store Errors

### Integration store fails to load

If the integration store is failing to load completely, there might be a few issues causing the problem.

#### Check and ensure the global proxy is setup

See Configuring a Proxy for more details:

- [Configuring Proxies](/v1/docs/configuring-proxies)

#### Check to ensure the `polarity_web` container can access the Integration Store

```shell
docker exec -it polarity_web bash
curl -v https://integration-store.polarity.io/api/repos
```

If there is a successful connection, please check the certificates to ensure they are valid and that the full CA cert chain is added to the server.

### Integration Store loads but fails to install integrations

If you are able to access the integration store, however are not able install integrations and are getting an error, it is usually one of the following reasons:

1. There is a missing cert in the CA cert chain path.
2. The `POLARITY_HOSTNAME` and/or the `POLARITY_WEB_HOSTNAME` is set incorrectly in the `/app/.env` file.
3. The server’s certificate was issued for a FQDN or IP address that doesn’t match the `POLARITY_HOSTNAME` or `POLARITY_WEB_HOSTNAME`.
4. The URL used to access the User Interface (either Web UI or Client software) doesn’t match the set FQDN in the `/app/.env`.
5. A combination of the above.

#### 1. Re-check your Certificate Authority certificates

Check your CA certificates to ensure the full paths are contained. See the CA Certificate section in the guide below:

- [Configure the Server SSL Certificates](/v1/docs/configure-the-server-ssl-certificates#ca-certificate-chains)

#### 2. Check and hostnames/IPs in the `.env` file

If the Store is not loading or not downloading integrations then there can be a hostname/IP mismatch in the `/app/.env` file. Please check the `/app/.env` file to ensure the `POLARITY_HOSTNAME` and `POLARITY_WEB_HOSTNAME` variables are set correctly.

- [Configure the Server FQDN](/v1/docs/configure-the-server-fqdn)

#### 3. Check your FQDN settings in the `/app/.env` file

Ensure the `POLARITY_HOSTNAME` and `POLARITY_WEB_HOSTNAME` parameters in the `/app/.env` are set to the correct FQDN, which must match the server certificate’s CNAME or one of the SANs. See the guides below:

- [Configure the Server FQDN](/v1/docs/configure-the-server-fqdn)
- [Configure the Server SSL Certificates](/v1/docs/configure-the-server-ssl-certificates)

#### 4. Double-check that you’re using the correct URL to access your Polarity Server

---

## Docker images are loaded but still getting an error when logging in

### Postgres and Redis listening for Docker IP

> [!WARNING]
> NOTE:
> 
> This only applies to Polarity Servers that have been ***upgraded*** from ***version 4*** to ***version 5***.

This is typically due to either Postgres or Redis not listening for the docker IP addresses. To check if this is occurring run the following commands.

Check the Docker IP address:

```shell
docker network inspect polarity_platform_net
```

Locate the "IPAM.Config" block to find the Gateway IP address (probably 172.18.0.1).

Once you have the IP address, run the following command to check and ensure Postgres and Redis are listening on the Docker Gateway IP:

```shell
netstat -anptu | grep “LISTEN”
```

You are looking for the following lines:

```shell
Postgres: {{gatewayIP}}:5432
Redis Metric Cache: {{gatewayIP}}:7379
Redis Integration Cache: {{gatewayIP}}:8379
```

If any of those lines are missing then we will need to add the Docker gateway IP to the configurations for Postgres or Redis.

#### Edit the Postgres Config File

Open the /var/lib/pgsql/15/data/postgresql.conf file for editing to configure Postgres to listen for the Docker gateway IP:

Locate the line that starts with "listen_addresses = ", and add the gateway IP:

```shell
listen_addresses = ‘127.0.0.1,{{gatewayIP address}}’
```

Restart Postgres:

```shell
systemctl restart postgresql
```

#### Redis Not listening

If Redis is not listening on those ports, then the most likely issue is that Redis is not running. Restart the Redis caches:

```shell
systemctl restart polarity-integration-cache 
systemctl restart polarity-metrics-cache
```

---

## Specific Error Troubleshooting

### Integration Cache Connectivity Lost

If when searching for integrations you see the following integration error:

```plaintext
connection has been lost with the integration cache
```

the Integration Cache is likely not running, or Docker is unable to connect to it.

You can re-establish the connection by restarting both caches:

```shell
systemctl restart polarity-integration-cache 
systemctl restart polarity-metrics-cache
```

The above error typically occurs after a server reboot if the Docker service starts before the Redis and/or PostgreSQL services. We recommend following this guide to ensure that the Redis cache services (including the integration cache) start after the Docker service on a server reboot to prevent this error from happening in the future:

- [Upgrade from Polarity Server v4](/v1/docs/upgrade-from-polarity-server-v4)