Troubleshooting
Error codes
Every error from the UI and the REST handlers carries a code. Meaning and handling, by category.
Every error response is {"detail": "<message>", "code": "<code>", "params": {...}}. The UI shows the message in the current language; REST callers branch on code. Splunk's admin framework wraps it in an HTTP 500 with a <class …>: prefix, which the UI strips; when parsing yourself, take the JSON after the first {.
| Code | Meaning | Handling |
|---|
forbidden | The role lacks params.capability (copilot_use / copilot_write / copilot_admin) | Ask a Splunk admin for the role |
read_only | Read-only role attempted a write | Same |
rate_limited | Over params.rate per minute per user | Wait params.seconds; tune [limits] |
| Code | Meaning | Handling |
|---|
license_required | Not activated; paid capabilities locked | Settings → License |
license_invalid | Signature / tamper check failed (params.reason) | Token truncated or not for this product; copy again |
license_expired | Expired | Renew |
license_revoked | Revoked | Contact sales |
license_host_mismatch | The offline licence is bound to another host | Re-issue with this host's fingerprint |
license_offline_grace_expired | Licence server unreachable beyond the grace period | Check outbound to license.reallysec.com:443 |
license_check_failed / license_unavailable | Verification impossible / SDK unavailable | See params.reason; usually files missing from bin/lib |
machine_id_unreadable | No hardware identifier readable | Inject /etc/machine-id in the container |
license_activate_failed | Activation refused (params.reason: seats used, fingerprint mismatch, wrong product…) | Per reason |
license_activate_error / license_deactivate_error | Exception during activation / deactivation | See reason |
feature_sealed | params.feature needs a licence: not activated, feature excluded, or key not delivered | Activate a licence with the feature; offline licences need the key at issue |
trial_terms_required | Terms not accepted | — |
trial_already_requested | This host already requested a trial | Extensions via sales |
trial_server_unreachable | Licence server unreachable | Check egress; retry later |
trial_rejected | Server refused (params.reason: email domain, rate limit…) | Per reason |
trial_pending | Submitted for review (params.request_id) | Wait for the email, paste the token |
| Code | Meaning | Handling |
|---|
alert_not_found | Alert missing or expired | Refresh |
alerts_or_index_required | Triage got neither alerts nor an index | — |
too_many_alerts | Over the batch cap | Narrow the window or count |
start_after_end | Report range starts after it ends | — |
channel_error | Channel send failed (params.reason is the channel's message) | See the inline hint |
deploy_rejected | Splunk refused the saved search (params.reason is splunkd's message) | Typically a Free licence rejecting alert.severity; invalid key or cron |
noise_no_backup | No suppression backup for the rule | Only rules applied from the page can be reverted |
advisor_no_backup | No rewrite backup for the saved search | Same |
onboard_no_sample | No sample events for the index / sourcetype | Change the scope or paste samples |
onboard_app_missing | Target app does not exist | [onboard] default_app or the page setting |
es_not_installed | No Enterprise Security; cannot write back | — |
notable_update_failed | ES notable_update returned an error | Check ES permissions (ess_analyst); params.reason |
tickets_not_configured | Ticketing not configured | Outbound channels → Ticketing |
tickets_disabled | [tickets] enabled = 0 | Edit the conf |
ticket_auth_failed | ServiceNow / Jira rejected the credentials | Re-enter; Jira wants an API token, not a password |
ticket_create_failed | Ticket creation failed (params.reason) | Required fields, permissions or host allow-list on the instance side |
| Code | Meaning | Handling |
|---|
internal_error | Handler exception (params.reason) | index=_internal component=PersistentScript copilot |
llm_error | Model call failed / non-JSON reply | Change model, turn thinking off, check provider health |
search_failed | Splunk search error (params.reason is splunkd's message) | Usually permissions or SPL syntax |
