Troubleshooting New and Existing Installs¶

This page collects the failures QIE hits both immediately after a fresh install and later on during ongoing operation: a service that stops shortly after startup, a launcher log that stops making sense against a newer JDK, a running channel that hits sporadic slowness under load. Entries below span both audiences; if you are chasing a very first-startup problem, keep reading. That is the most common case and the one described next.

If QIE installs cleanly but the engine fails shortly after start. The console at http://localhost is reachable for the first few minutes and then the service stops. The most common cause is that QIE cannot establish a connection to its configured database. The engine performs a startup health check against the database; if the check keeps failing the service shuts itself down.

Startup errors are recorded in qieLauncher.log, which usually shows a stack trace ending in something like:

Caused by: java.net.ConnectException: Connection refused: getsockopt

This means the host and port in the -Dconnection.url Java Option are reachable on the network but nothing is listening, which is almost always a problem with the database server, not QIE.

Note

qieLauncher.log lives in the QIE home directory's log folder, alongside qie.log. The launcher log is the right place to look for startup failures because the engine may not get far enough to write to qie.log. To find the QIE home directory, open the QIE Service Manager and look for the -Dqie.home value under Java Options.

Confirm the database is running and reachable¶

Before changing anything in QIE, verify that you can reach the database from the QIE host on the configured port (default 3306 for MariaDB/MySQL, 1433 for MSSQL).

Linux / MacWindows PowerShell

telnet <db-host> 3306
mariadb -h <db-host> -u qie -p

Test-NetConnection -ComputerName <db-host> -Port 3306
mariadb -h <db-host> -u qie -p

If telnet / Test-NetConnection fails, the problem is below QIE. Work through the checklist below until both commands succeed, then start the QIE service.

Common causes¶

Database service is not running¶

On Windows, open Services and confirm the MariaDB (or MySQL / SQL Server) service is Running and set to Automatic start. The QIE installer does not manage the database service lifecycle.

Database service starts after QIE on reboot¶

The QIE Windows service has no declared dependency on the database service, so after a reboot the two services start in parallel and QIE can lose the race. To fix, add the database service as a dependency of the QIE service so Windows starts it first. From an elevated Command Prompt:

sc config QIE depend= MariaDB

Substitute the actual service name of your database (MySQL80, MSSQL$SQLEXPRESS, etc.) if it is not MariaDB.

Database is bound to `localhost` only¶

By default MariaDB and MySQL on some Linux distributions bind to 127.0.0.1 and refuse remote connections. If QIE is installed on a different host from the database, or if -Dconnection.url uses the host's external IP, edit the database configuration (my.cnf / my.ini) and either remove skip-networking and set bind-address = 0.0.0.0, or set bind-address to the specific interface QIE connects on. Restart the database service after the change.

Wrong host, port, or database name in `-Dconnection.url`¶

Open the QIE Service Manager, go to the Startup tab, and inspect the -Dconnection.url value. The format is:

-Dconnection.url=jdbc:mariadb://<host>:<port>/<database>

A typo in the host name, a non-default port (some MariaDB installs use 3307), or a database name that does not exist all surface as Connection refused or an immediate authentication failure. See Alternate Database for the full set of database-related Java Options.

Firewall blocking the database port¶

If QIE and the database are on different hosts, Windows Defender Firewall (or the Linux firewall, or a corporate firewall) must allow inbound TCP on the database's port. Add an explicit allow rule on the database host for the QIE host's IP address.

Database user cannot connect from the QIE host¶

The default qie user created by the express installer is granted access only from localhost. If QIE and the database are on different hosts, create or grant the qie user from the QIE host's address:

CREATE USER 'qie'@'%' IDENTIFIED BY '<password>';
GRANT ALL PRIVILEGES ON qie.* TO 'qie'@'%';
FLUSH PRIVILEGES;

Replace '%' with the QIE host's IP address for a tighter grant.

`.mdmp` crash-dump files accumulating in the QIE directory¶

Windows generates a .mdmp (minidump) file whenever the Java process running QIE terminates ungracefully: a power loss, a Task Manager "End process," a reboot without stopping the QIE service first. The files themselves are diagnostic artifacts; they are safe to delete once they are no longer needed for a support case. If they are piling up faster than expected, that is a signal that the QIE service is being shut down non-gracefully somewhere in the routine.

The clean shutdown path is to stop the QIE service before shutting the host down:

Windows (elevated command prompt):
```
net stop QIEService
```
Linux (systemd):
```
sudo systemctl stop qie
```

If the host is rebooted for OS patching, weekly maintenance, or similar, wire the QIE service stop into whatever automation triggers the reboot so QIE gets a clean shutdown every time.

IllegalAccessError from com.qvera.launcher.utils.QieLauncher¶

An older qieLauncher accesses internal JDK packages (sun.security.action) that later Java releases no longer expose to unnamed modules. If qieLauncher.log starts with a line like:

java.lang.IllegalAccessError: class com.qvera.launcher.utils.QieLauncher$LogFormatter (in unnamed module @0x...) cannot access class sun.security.action.GetPropertyAction ...

refresh qieLauncher on the QIE host. See Updating qieLauncher on Windows or Updating qieLauncher on Linux/Mac. A modern qieLauncher uses standard APIs and does not need the workaround.

If the launcher cannot be refreshed immediately, open the module to unnamed code as a temporary workaround by adding a Java option to the QIE Service Manager Startup tab:

--add-opens=java.base/sun.security.action=ALL-UNNAMED

Remove the option once the launcher has been refreshed.

Auto-update fails to complete¶

QIE downloads product updates from qvera.com. Failures usually surface as a stalled or partial download in qieLauncher.log, or an error banner in the QIE console reporting the update could not be applied. Two common causes:

A firewall, corporate proxy, or intrusion-detection appliance is blocking the connection to qvera.com outright, or is stripping intermediate chunks inside an otherwise-successful session. Add qvera.com (and qiecheckin.com, used for the license heartbeat) to the allow-list. See Outbound Network Access for the full list.
The QIE host's outbound HTTPS route is intermittently up. Retry the auto-update after network stability is confirmed.

If the proxy/appliance cannot be adjusted, apply the update manually:

Contact Qvera support for the installer that matches the target QIE version.
Stop the QIE service on the QIE host.
Run the installer as an administrator.
Start the QIE service and confirm the new version in Help -> About.

Random slowness on Linux under load¶

Sporadic multi-second stalls in channel processing on Linux hosts (bare metal or VMs) can be caused by kernel Transparent Huge Pages (THP) compaction competing with the JVM for memory. Check the current setting:

cat /sys/kernel/mm/transparent_hugepage/enabled

If the value in square brackets is [always], THP compaction is on. Switch it to madvise (recommended for JVM workloads) or never:

echo madvise | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
echo madvise | sudo tee /sys/kernel/mm/transparent_hugepage/defrag

The change is not persistent across reboots. To make it permanent, add both echo commands to a boot-time hook (an /etc/rc.local entry, a systemd tmpfiles.d rule, or a small systemd unit that runs Before=qie.service). Restart QIE after the change takes effect.

First startup takes longer than usual¶

The first QIE startup against a brand-new install is slower than subsequent startups for two reasons:

The database server may still be initializing on its first boot. MariaDB and MySQL resize their data files and may not accept connections for a minute or two after the service reports as started.
QIE connects to an empty schema on first run and creates all of its configuration and audit tables before the engine comes online. This schema creation can take several minutes on slower disks or against a remote database.

This is expected and is not a failure. Wait until the database accepts a telnet connection on its port, start the QIE service manually from the QIE Service Manager, and give it time to come up before assuming startup has failed. qieLauncher.log continues to grow while the engine is initializing. As long as new lines are being written, startup is progressing.

If the problem persists¶

Open qieLauncher.log in the QIE home directory's log folder and locate the first failed startup attempt. Capture the full Caused by: chain, which identifies the host, port, and underlying socket error.
If qieLauncher.log is empty or does not point at the database, check qie.log in the same folder for an engine-level exception thrown after the connection was established.
Contact Qvera support with the relevant section of those logs and the contents of the Startup tab's Arguments field (with the database password redacted).