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

# GermainUX Enterprise Troubleshooting

> Most GermainUX Enterprise issues can be diagnosed using the GermainUX Workspace and application logs.

Service
`Enterprise`

Availability
2024-01-01

> [card] [Common issues](#common-issues)
>
> Frequent problems and fixes

> [card] [Connection errors under high load](#connection-errors-under-high-load)
>
> Ephemeral port exhaustion fixes

> [card] [Network-port conflict](#network-port-conflict)
>
> Tomcat port clashes

> [card] [Contact GermainUX Support](#contact-germainux-support)
>
> Information to send support

**GermainUX Enterprise Troubleshooting**

Most GermainUX Enterprise issues can be diagnosed using the GermainUX Workspace and application logs. This section covers common startup, connectivity, and resource-exhaustion problems affecting on-premise deployments.

## Before troubleshooting

Before restarting services or changing the configuration:

* Record the time the issue occurred.
* Preserve the relevant GermainUX and Tomcat logs.
* Identify any recent deployment, Java, network, or configuration changes.
* Confirm which GermainUX components are affected.
* Check the availability of all required dependencies.
* Verify available CPU, memory, disk space, and network ports.

Restarting a service may temporarily restore availability while hiding the original cause. Review and preserve the logs first whenever possible.

## Initial checks

Confirm that the required components are running and accessible:

* GermainUX datastore
* ZooKeeper
* Kafka—or ActiveMQ for legacy releases
* Hazelcast
* Germain Enterprise on Tomcat
* GermainUX Services
* Germain nodes and monitoring components

Verify that they were started in the correct order and that their logs contain no connection or configuration errors.

## Common issues

| Symptom | Likely cause | Troubleshooting guide |
| - | - | - |
| Intermittent connection errors, particularly after monitoring volume increases | Available TCP ports are exhausted or connections remain in `TIME_WAIT` too long | Avoid TCP exhaustion on GermainUX Enterprise |
| Germain Enterprise no longer starts after Java was upgraded or moved | The Tomcat service still references the previous Java runtime or installation path | GermainUX Enterprise does not start after a Java upgrade |
| Germain Enterprise cannot start because its HTTP or HTTPS port is unavailable | Another process is already using the configured Tomcat port | GermainUX Enterprise does not start because of a network-port conflict |

## Germain Enterprise does not start

Review the Tomcat startup log and check for:

* An incorrect or unavailable Java runtime
* A port already used by another process
* Invalid Tomcat XML configuration
* Missing or inaccessible configuration files
* Insufficient JVM memory
* An unavailable ZooKeeper, Kafka, Hazelcast, or datastore connection

> [accordion] Show all 9
>
> * Incorrect service-account permissions
> * Invalid certificates or truststores
> * Insufficient disk space

Focus on the first relevant exception. Later errors are often consequences of the original failure.

## Connection errors under high load

A substantial increase in monitored data can create many simultaneous TCP connections and exhaust the available ephemeral ports on the Germain Enterprise server.

Typical symptoms include:

* Intermittent Workspace or service connection errors
* Requests that time out during periods of high volume
* Many connections remaining in `TIME_WAIT`
* Normal behavior returning after traffic decreases or the server restarts

Possible corrective actions include:

* Increasing the operating system’s available TCP port range
* Reducing the TCP `TIME_WAIT` duration
* Increasing the Apache proxy server’s available worker threads
* Correcting excessive connection creation or missing connection reuse
* Scaling GermainUX Enterprise when sustained traffic exceeds capacity

On Windows, the linked troubleshooting procedure provides example registry settings for `MaxUserPort` and `TcpTimedWaitDelay`.

> [!NOTE]
>
> Changes to Windows TCP registry settings affect the entire server. Back up the registry and obtain infrastructure approval before applying them. Do not treat operating-system tuning as a substitute for correcting connection leaks or inadequate capacity.

## Enterprise does not start after a Java upgrade

When Java is upgraded or moved, the Windows Tomcat service may continue referencing the previous Java path.

Open the Tomcat service configuration utility:

```text theme={null}
C:\TOMCAT_DEPLOYMENT_FOLDER\bin\tomcat8w.exe //ES/GermainServer
```

Verify the Java Virtual Machine path and related Java options, save the changes, and restart the Germain service.

After restarting, confirm in the logs that Germain Enterprise is using the expected Java version and path.

The utility name may differ if the deployment uses another Tomcat service version or service name.

## Network-port conflict

Germain Enterprise cannot start if another process already uses one of its configured Tomcat ports.

### Identify the process on Linux

```text theme={null}
netstat -apn | grep <port-number>
```

If `netstat` is unavailable, use:

```text theme={null}
ss -ltnp | grep <port-number>
```

### Identify the process on Windows

```text theme={null}
netstat -ano -p tcp | find "<port-number>"
tasklist /fi "pid eq <process-id>"
```

### Identify the process with PowerShell

```text theme={null}
Get-NetTCPConnection -LocalPort <port-number> |
    Select-Object LocalAddress, LocalPort, State,
        @{Name="PID"; Expression={$_.OwningProcess}},
        @{Name="Process"; Expression={
            (Get-Process -Id $_.OwningProcess).ProcessName
        }} |
    Sort-Object LocalPort |
    Format-Table
```

Review the Tomcat connectors in:

```text theme={null}
<TOMCAT_HOME>/conf/server.xml
```

Depending on the deployment, the configuration directory may be referenced as `conf`, not `config`.

Search for:

```text theme={null}
<Connector
```

Resolve the conflict by either:

* Reconfiguring the other application to use a different port, or
* Assigning an available port to the affected Tomcat connector

If the Tomcat port changes, also update any reverse proxy, firewall, load balancer, monitoring, or client configuration that references the previous port.

## Workspace is unavailable but Tomcat is running

Check:

* The GermainUX web applications deployed successfully.
* The Tomcat logs contain no deployment exceptions.
* The Workspace context path is correct.
* The reverse proxy or load balancer can reach Tomcat.
* Authentication services are available.
* The database and ZooKeeper connections are operational.
* Browser requests are not failing with `404`, `502`, `503`, or TLS errors.

Test direct access to Tomcat when permitted. If direct access works but the public URL does not, investigate the reverse proxy, load balancer, DNS, or TLS configuration.

## Data is not appearing

If the Workspace is accessible but no new data appears, verify:

* Monitoring components are sending data.
* GermainUX Services are running.
* Kafka—or legacy ActiveMQ—accepts messages.
* Storage and analytics services are processing data.
* The datastore is available and writable.
* Queue or topic backlogs are not increasing.
* The correct environment and application configuration are active.
* Time synchronization is correct across all hosts.

Compare timestamps across the monitoring component, messaging system, GermainUX Services, and datastore logs to identify where processing stops.

## After applying a fix

Confirm that:

* Germain Enterprise starts without errors.
* The Workspace and Configuration Console are accessible.
* All GermainUX Services are running.
* Infrastructure dependencies remain connected.
* New telemetry is collected and processed.
* Queue or topic backlogs remain stable.
* No repeated connection, Java, or port errors appear.
* CPU, memory, disk, and TCP usage remain within acceptable limits.

## Contact GermainUX Support

If the problem persists, provide:

* GermainUX version
* Tomcat and Java versions
* Operating system
* Deployment topology
* Relevant logs covering the failure
* Exact timestamps

> [accordion] Show all 11
>
> * Recent configuration or infrastructure changes
> * Service status
> * Port and process information
> * CPU, memory, disk, and TCP-connection statistics
> * Steps required to reproduce the issue

Remove passwords, tokens, private keys, and other secrets before sharing configuration files or logs.

For assistance, [contact GermainUX Support](https://docs.germainux.com/main/support.md).

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/main/support.md)
>
> The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

> [card] Can't find what you need?
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.