Troubleshooting
Install-time failures, API error codes in playbook runs, data that does not appear, and where to escalate — with diagnostics that work.
Troubleshooting Documentation
The failure modes below are ordered the way you'll hit them: install-time errors first, then API errors in playbook runs, then data that doesn't show up where you expect it.
Install-time failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Wizard rejects the secret URI | Trailing whitespace, a ?api-version=… query string, or a /keys///certificates/ URI instead of /secrets/ | Paste the clean secret URI; the version suffix is optional |
Deploy fails with AuthorizationFailed | Installer lacks role-assignment rights | Get Owner or User Access Administrator on the resource group |
| Workspace missing from the wizard dropdown | Workspace is in a different resource group, or CLI-enabled Sentinel missed the legacy SecurityInsights resource | Install into the workspace's resource group; confirm the workspace appears in the Sentinel workspace picker |
| Playbook runs fail with 403 from Key Vault | Vault uses access policies, not RBAC | Switch the vault to the Azure RBAC permission model, or grant the identities via access policy |
API errors in playbook runs
Playbooks retry transient failures with exponential backoff (3 attempts) and log errors without failing the incident workflow.
| Code | Meaning | What to do |
|---|---|---|
400 | Malformed input — wrong indicator type for the playbook, or reserved Cypher keywords in the input | Validate the input format; test with a simple indicator like 1.1.1.1 |
401 | The Key Vault secret does not hold a valid Whisper API key | Set the real key: az keyvault secret set --vault-name <vault> --name whisper-api-key --value <key>, then re-run |
502 / 503 | Transient Whisper API or upstream feed issue | Retries usually recover it |
Check that the API is reachable from wherever you are testing:
curl -sS -X POST https://graph.whisper.security/api/query \
-H 'Content-Type: application/json' \
-H 'User-Agent: whisper-sentinel-diagnostic/1.0' \
-d '{"query":"CALL whisper.version()"}'
A 200 carrying version and buildTime means the endpoint is up and reachable from that host.
It does not tell you whether your key is good. the endpoint answers 200 to a well-formed request with a valid key, with a wrong key, and with no key at all. A key problem surfaces as the 401 above, in the playbook run — not here.
Data not appearing
A custom table doesn't exist yet. Tables are created on first write. Run any playbook on a test incident, wait a few minutes, then check:
WhisperThreatIntel_CL | take 1
A playbook succeeded but wrote nothing. Open the Logic App → Runs → the run in question, and check the table-write action for a schema or DCR error. Verify the whisper-* data collection rules exist in the resource group.
WhisperHistory_CL stays empty. The daily WHOIS and BGP pipelines ship with empty watchlists and collect nothing until you set them — see Configuration.
Workbook panels are empty. The Incident Enrichment Audit workbook reads Logic App telemetry from AzureDiagnostics; rows appear a few minutes after the first playbook run with diagnostics enabled. Other workbooks need rows in the Whisper tables first — run the watchdog query on Data Reference to see which of the four are still empty.
It names all four tables rather than matching them by pattern, and that is the part to keep if you adapt it. These tables are created on first write, so a table nothing has written yet is not empty, it is absent, and a query that can only see the tables that exist drops it from the result silently. That is exactly the table you are looking for when a panel is blank; the outer join lists all four every time.
An automation rule never fires its playbook. The one-time playbook-permission grant is missing — step 1 of Configuration.
Escalating
- Solution bugs and feature requests: Support
- A column that is absent, empty, or not the type you expected: check it against the table contracts on Data Reference before filing — several columns are documented as unwritten.
- API-side issues (include the error code, request ID, and the indicator you tested): Support