Troubleshooting
Install-time failures, API error codes in playbook runs, data that doesn't appear, and where to escalate.
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 |
408 | Query exceeded its timeout — expected occasionally for BGP history | The playbook retries with a simplified query on its own; persistent timeouts usually mean quota throttling |
429 | Daily API quota exceeded — all playbooks fail at once, with a resetAt in the response | Wait for the daily reset, scope automation rules to high-severity incidents, or upgrade the plan |
502 / 503 | Transient Whisper API or upstream feed issue | Retries usually recover it; check status.whisper.security if it persists |
Test the key directly when in doubt:
curl -H "X-API-Key: <your-key>" https://graph.whisper.security/api/actuator/health
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:
union withsource=WhisperTable Whisper*_CL
| summarize Rows = count(), Latest = max(TimeGenerated) by WhisperTable
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: github.com/whisper-sec/whisper-sentinel
- API-side issues (include the error code, request ID, and the indicator you tested): Support
- Live service status: status.whisper.security