Troubleshooting

This chapter covers the most common operational problems, their symptoms, and the steps to fix them. For general log locations and health check endpoints see Diagnostics.

Service startup

Energy SOAR Base does not start

Symptom: systemctl status energysoar shows failed or the service exits immediately.

Check that Cassandra and Elasticsearch are running first:
systemctl status cassandra
systemctl status elasticsearch
Energy SOAR Base fails to start if either data store is unavailable. Start them first, then start Energy SOAR:
systemctl start cassandra
systemctl start elasticsearch
systemctl start energysoar

Elasticsearch health check returns an error

Symptom: curl -I http://127.0.0.1:9200/ does not return HTTP 200.

Check the Elasticsearch log:
journalctl -u elasticsearch --since "10 minutes ago"
tail -n 50 /var/log/elasticsearch/elasticsearch.log
Common causes: insufficient heap memory, disk space below the watermark threshold, or a corrupted index. Increase the JVM heap in /etc/elasticsearch/jvm.options or free disk space, then restart Elasticsearch.

Automation service fails to start

Symptom: systemctl status cortex shows failed.

Check the Automation log:
tail -n 50 /var/log/cortex/application.log
Automation also requires Elasticsearch. Confirm http://127.0.0.1:9200/ is reachable before starting Automation.

License

Platform shows no license or limited features after installation

Symptom: features are restricted or an unlicensed notice appears in the UI.

Confirm the license file is present in /etc/energysoar/:
ls /etc/energysoar/energysoar_*
If no file is found, copy the license file into that directory. The service reloads the license automatically every 5 minutes. To apply it immediately:
systemctl restart energysoar

Updated license is not applied

The installer reads the license file from the directory configured in /etc/energysoar/application.conf.d/license.conf. Only one license file may be present in that directory at a time. Remove the old file before adding the new one:
rm /etc/energysoar/energysoar_*
Copy the new license file into /etc/energysoar/, then restart the service.

Login and authentication

“Login Failed” banner appears with correct credentials

Check /var/log/energysoar/application.log for AuthenticationError. Common causes: wrong organisation assigned to the user, account locked, or an LDAP/AD misconfiguration.

SSO button does not appear on the login page

The button is rendered only when the ssoStatus configuration flag is set to true in the authentication provider configuration. Verify the SSO settings in /etc/energysoar/application.conf.d/.

Session expires and the user is redirected to login

The session inactivity timeout is 1 hour. A warning appears 10 minutes before the session ends. To extend the timeout, edit the session block in /etc/energysoar/application.conf.d/ and restart the service.

Automation and analyzers

“Configure Plugins” link is missing from the sidebar

The sidebar item requires the managePlugins permission. Confirm the user’s organisation profile includes that permission, or grant it in Organisation > Profiles.

“No Analyzer Available” when running analyzers on an observable

Likely causes:

The Automation module is disabled in /etc/energysoar/application.conf.d/. The line play.modules.enabled += org.emca.energysoar.connector.cortex.CortexModule must be uncommented.

The Automation API key configured under cortex.servers[].auth.key is wrong or expired. Generate a new API key in Automation and update the configuration.

The observable type is not supported by any installed analyzer.

After editing the configuration, restart Energy SOAR Base.

Analyzer job stays in “Waiting” and never starts

Check that the Automation service is running:
curl -I http://127.0.0.1:9001/automation
Confirm the URL and API key in /etc/energysoar/application.conf.d/ match the Automation server. The default job timeout is 30 minutes; jobs waiting longer than that are likely stuck due to a connectivity problem.

Analyzer job fails immediately

Check /var/log/cortex/application.log. Common cause: the Docker runner is not available. Automation uses runners = [docker, process] — if the Docker daemon is not running, only process-mode runners execute. Start Docker or switch to runners = [process] in the Automation configuration.

MISP integration

MISP integration does not connect

The MISP module is disabled by default. The line play.modules.enabled += org.emca.energysoar.connector.misp.MispModule in /etc/energysoar/application.conf.d/ must be uncommented. Also confirm the URL and API key under the misp.servers block are correct.

Observable export to MISP fails

The log reports: Export on MISP connection <id> is denied by configuration. The exporting organisation is not authorised to push to that MISP connection. Check the misp.servers[].wsConfig and organisation permissions in /etc/energysoar/application.conf.d/.

Only IOC-flagged observables appear in MISP

Only observables with the Is IOC flag set are exported to MISP. This is by design. To export an observable, open it in the Observables tab and enable Is IOC.

File attachments

File upload fails with a size error

The installed default is 1 GB, set in /etc/energysoar/application.conf.d/service.conf:
play.http.parser.maxDiskBuffer: 1GB
To change the limit, edit that value and restart Energy SOAR Base.

Downloaded file observable is not a ZIP archive

Downloaded file observables are delivered as password-protected ZIP archives. The password is malware. Use any ZIP utility that supports password-protected archives to extract the file.

nginx and TLS

Browser shows a certificate warning on first access

The installer generates a self-signed certificate at /etc/energysoar/ssl/nginx-selfsigned.crt. Browsers warn on untrusted certificates. To replace it with a valid certificate, follow the custom TLS certificate procedure and update /etc/nginx/conf.d/energysoar.conf.

nginx returns 502 Bad Gateway

A 502 response means nginx reached a backend that is not listening. Check which service is down:
curl -I http://127.0.0.1:9000/base          # Energy SOAR Base
curl -I http://127.0.0.1:9001/automation    # Automation
Restart the failing service. Check /var/log/nginx/error.log for which upstream failed.

Logs and verbose output

Log verbosity is too low to diagnose a problem

The root log level is INFO by default, set in /etc/energysoar/logback.xml. To enable DEBUG output for a specific subsystem, add a <logger> block and set its level to DEBUG, then restart the service. Revert after diagnosis.

Collecting a diagnostic bundle for support

Run the status script to collect a snapshot of the system:
/opt/energysoar/lib/extra/energysoar_status.sh
The script collects CPU and memory usage, disk usage, systemd journal logs for all services, HTTP health check responses, and Java version. The output is written to /tmp/soar_logs.tar.gz. Attach that archive when reporting an issue.