# Troubleshooting

> Troubleshoot the Whisper Splunk add-on: common errors, diagnostic commands, log locations, file precedence rules, and where to escalate for support.

*Source: https://www.whisper.security/docs/integrations/splunk/troubleshooting*
*Published: 2026-04-06*
*Last updated: 2026-09-20*

---
## Quick checks
Run these first when something looks off.
Start with the two searches under [Verify it works](/docs/integrations/splunk/install#verify-it-works) on the install page: one confirms the app is installed and enabled, the other confirms the search commands are registered and the account reaches the API. If the second returns no result the add-on is not reaching the API.
Then check for log activity:
```spl
index=_internal sourcetype="ta_whisper_graph"
| stats count by log_level
```
Zero rows here means no add-on component has run yet, or you are searching the wrong time range.
## Common errors
### `WhisperAPIRequestError: Whisper API error 401`
The API key is invalid or missing. Re-check it under **Apps > Whisper Security TA > Configuration > Account** and use **Test Connectivity**.
### `whisperquery: Query validation failed: query must include LIMIT clause`
Cypher queries must include a `LIMIT N` clause. This is a guardrail to keep search-time queries bounded.
### Test Connectivity reports an unrecognised key
The API accepted your request but did not recognise the key, so it answered as though no key had been sent. Common causes: trailing whitespace pasted in with the key, a key from a different environment, or a key that has expired. Re-copy it from [console.whisper.security](https://console.whisper.security/sign-in) and paste it again.
### App shows "not fully configured" after saving the account
The `is_configured` flag in `local/app.conf` was not flipped by the UCC setup hook. Save the account again from the Configuration page (the hook will retry). If it still does not clear, set the flag manually:
```bash
curl -k -u admin:<password> \
  https://localhost:8089/servicesNS/nobody/TA-whisper-graph/configs/conf-app/install \
  -d is_configured=true
```
Refresh the browser.
### `whisperflush` returns a permission error
The `whisperflush` command requires `admin` (Enterprise) or `sc_admin` (Cloud) capabilities. Run it as a user with one of those roles, or have an admin run it for you.
### Enrichment returns stale data
Flush the cache. The default TTL is one hour:
```spl
| whisperflush collection=cache
```
### Modular inputs not collecting data on Splunk Cloud Classic
Classic uses an event-based pipeline because the IDM cannot write to KV Store directly. Confirm:
1. Modular inputs are enabled on the IDM.
2. Events are landing: `index=whisper sourcetype=whisper:threat_intel`.
3. The disabled-by-default populator saved searches (`Whisper - Populate IP Threat Intel KV Store`, `Whisper - Populate Domain Threat Intel KV Store`, `Whisper - Populate Precomputed Enrichment KV Store`) are enabled and scheduled to run after the modular-input collection interval.
### KV Store not replicating across SHC members
Verify replication status:
```spl
| rest /services/kvstore/status
| table title currentStatus replicationStatus
```
Confirm `server.conf` includes `[shclustering] conf_replication_include.ta_whisper_graph_settings = true` (the TA ships this). If it is missing on one member, push the SHC bundle from the deployer again.
## Where the logs live
Operational logs go to the `_internal` index under sourcetype `ta_whisper_graph` (the UCC default). Do not confuse this with the `whisper:*` sourcetypes used for indexed data.
```spl
index=_internal sourcetype="ta_whisper_graph" log_level=ERROR
| table _time component message
| sort -_time
```
On disk:
```bash
# Cloud Victoria + recent Enterprise / Cloud Classic
tail -f $SPLUNK_HOME/var/log/splunk/TA-whisper-graph/ta_whisper_graph.log
# Older deployments (fallback path)
tail -f $SPLUNK_HOME/var/log/splunk/ta_whisper_graph.log
```
To raise log verbosity for diagnosis, go to **Settings > Server Settings > Server Logging**, search for `whisper`, and set the level to DEBUG. Set it back to INFO when you are done — DEBUG is chatty.
## File-precedence gotchas
Splunk merges configuration from `default/` (shipped) and `local/` (admin overrides), with `local/` winning.
Safe to override in `local/`:
* `macros.conf` — thresholds, time ranges, the `whisper_index` macro
* `savedsearches.conf` — enable/disable, schedules, alert conditions
* `inputs.conf` — modular input intervals, target index per input
* `authorize.conf` — `whisper_user` role tweaks
Do **not** override these. You will break command registration, KV Store schemas, CIM aliases, or app metadata:
* `commands.conf`
* `transforms.conf`
* `collections.conf`
* `props.conf`
* `app.conf`
## Collecting logs for support
Before opening a ticket, gather:
```spl
index=_internal source=*ta_whisper_graph.log earliest=-24h
| table _time log_level component message
| sort -_time
```
```spl
index=_internal source=*splunkd.log ExecProcessor whisper earliest=-24h
| table _time log_level message
```
```bash
$SPLUNK_HOME/bin/splunk diag --collect app:TA-whisper-graph
```
The diag bundle includes app config, logs, and KV Store metadata, but not credentials or customer data.
## Getting help
* [Support](/docs/support) — where to send the diag bundle and what to include with it

---

## Known limitations

Splunk-specific:

- **No prebuilt detection pack ships.** Saved searches are disabled-by-default templates customers clone. See [Saved Searches](/docs/integrations/splunk/reference#saved-searches).
- **ES integration is opt-in.** KV-store populators and RBA hooks are disabled by default. See [Enterprise Security Integration](/docs/integrations/splunk/es-integration).
- **AppInspect.** The package is checked with the `splunk-appinspect` CLI against both the `precert` and the `cloud` tag sets, with zero failures. Those are local runs — the reports carry `request_id: null`, which is what separates a CLI run from Splunk's hosted vetting service, and the add-on has not been through the hosted service. Adding custom Python libraries or native binaries means re-running the checks before the package ships.