Troubleshooting
Error codes
Every error from the UI and the API carries a code. Look up each code's meaning and remedy by category.
Every error response is {"detail": "<message>", "code": "<code>", "params": {...}}. The UI shows the message in the current language; API clients branch on code. Below, the codes you may meet, grouped by scenario.
Login and permissions
| Code | Meaning | Remedy |
|---|---|---|
login_required | Not logged in or session expired | Log in again |
bad_credentials | Wrong username or password | — |
login_throttled | Too many failed logins | Wait 5 minutes |
default_password_refused | Factory password still in use; remote login refused | Set RST_ADMIN_PASSWORD_HASH; RST_ALLOW_DEFAULT_PASSWORD=1 for a LAN trial |
password_login_disabled | SSO is on, password login is off | Use the SSO entry |
read_only | Viewer role cannot change this | Ask an admin |
admin_role_required / admin_login_required / admin_session_or_token_required | No admin rights | Log in as admin, or send X-RST-Admin-Token from ops tooling |
admin_group_required | SSO: not in a RST_RBAC_ADMIN_GROUPS group | Have the IdP admin add the group |
sso_identity_required | SSO on but no verified identity on the request | Log in through SSO; check oauth2-proxy |
csrf_rejected | Cross-site request refused | Act from the product page itself |
rate_limited | Rate limit hit | Wait params.seconds; raise RST_RATELIMIT_* for large teams |
user_db_not_configured / password_in_env_only | No user table; single-account deployments keep the password in .env | Set RST_USER_DB_URL, or regenerate the hash as instructed |
user_exists / user_not_found / unknown_role / username_required | User-management parameter problems | — |
last_admin_locked / last_admin_undeletable | The last admin cannot be disabled / demoted / deleted | Create another admin first |
cannot_disable_self / cannot_delete_self | Cannot disable / delete yourself | — |
password_too_short / password_min_length / current_password_wrong | Password under 8 characters; current password wrong | — |
password_change_not_supported | SSO accounts cannot change passwords here | Change it in the IdP |
Licence and quota
| Code | Meaning | Remedy |
|---|---|---|
feature_needs_standard / incident_report_needs_standard / platform_checkup_needs_standard | params.feature needs Standard or higher | Activate a licence |
feature_sealed | No licence, or the licence lacks this feature; the engine cannot be unsealed | Activate a licence that includes it |
trial_quota_exhausted | Daily unactivated quota (params.limit) used up | Tomorrow, or activate |
license_invalid | Signature / decryption / tamper check failed | Ask sales to re-issue |
license_expired | More than 7 days past expiry; service locked | Renew |
license_revoked | Revoked | Contact sales |
license_heartbeat_lost | No heartbeat for 7 days; service locked | Check the network to the licence server |
license_status_abnormal | Abnormal state | See the License page |
machine_id_unreadable | Hardware identifier unreadable | Check the /etc/machine-id mount |
license_activate_failed / license_activate_error / license_deactivate_error | Activation / deactivation refused or failed (params.reason: no seats left, fingerprint mismatch, wrong product…) | Act on the reason |
QRadar
| Code | Meaning | Remedy |
|---|---|---|
qradar_not_configured | No Console URL / token | Settings |
qradar_url_invalid / qradar_url_not_string | Console URL is not a full http(s) URL | — |
qradar_unreachable | Cannot reach the Console | Check QRADAR_URL, port 443, certificate verification |
qradar_auth_failed | 401, SEC token invalid or expired | Replace the token |
qradar_forbidden | 403, the token's role lacks this endpoint (params.reason) | Token permissions |
qradar_timeout | Ariel search cancelled after params.seconds s | Narrow the window / add a log-source condition; RST_AQL_TIMEOUT_SECONDS |
qradar_aql_error | QRadar rejected the AQL (params.reason is the Console's message) | Open the AQL and fix it, or "Let AI repair with the error" |
qradar_search_failed / qradar_request_failed | Ariel search / other request failed (params.reason) | See the reason |
alert_not_found / offense_not_found / offense_update_failed | Offense missing; close / note / assign failed (params.reason) | A failed close usually means the token lacks offense write rights, or someone closed it first |
rule_not_found | Rule does not exist | — |
AQL validation
| Code | Meaning | Remedy |
|---|---|---|
aql_empty | No AQL in the request | — |
aql_not_select | SELECT only | Rewrite |
aql_multiple_statements | One statement at a time | Drop everything after the semicolon |
aql_bad_source | Only events / flows, not params.source | — |
aql_validation_failed | Other read-only check failed (params.reason) | Rewrite |
log_source_not_whitelisted | References log source params.name outside the whitelist (params.patterns); reason=unbounded means it could not be scoped automatically (subselect / catalogue unavailable / whitelist expands past 50) | Add the source in Settings, or scope LOGSOURCENAME() in the AQL |
Model
| Code | Meaning | Remedy |
|---|---|---|
llm_generation_failed | Model call failed (params.reason) | Check provider status in AI settings |
llm_timeout | Model call timed out | Raise the provider timeout; send fewer clusters |
llm_first_token_timeout | No answer started within params.limit_s s; aborted | Rephrase and retry; lower reasoning effort |
providers_empty / model_required | Provider list empty / model missing | Configure at least one |
connection_test_failed | Connection test failed (params.reason) | See the reason |
Feature calls
| Code | Meaning |
|---|---|
investigation_failed / triage_failed / detection_rule_failed / report_generation_failed / incident_report_failed / platform_checkup_failed / suggest_angles_failed | The feature failed; details in params.reason |
detection_rule_rejected | The model declined (intent unclear) |
too_many_alerts | At most params.cap per triage run |
alert_empty / cluster_empty / investigation_empty / incident_input_required | No offenses / clusters / investigation in the request |
conversation_not_found / analysis_record_not_found | Conversation / record missing or expired |
explain_log_failed / explain_result_failed / nothing_to_explain / alerts_aggregate_failed | Explanation failed; nothing to explain; offense overview aggregation failed |
question_empty / query_empty / doc_empty / alerts_not_list / feedback_persist_failed | Missing question / AQL / event; alerts not an array; feedback not stored |
size_out_of_range / limit_out_of_range / top_k_out_of_range / offset_negative / invalid_time / start_after_end | Parameter out of range or invalid time |
Notifications
| Code | Meaning | Remedy |
|---|---|---|
push_failed | Delivery failed (params.reason) | See the delivery log |
delivery_not_retryable / notify_target_not_found | This delivery cannot be retried; target missing | — |
webhook_must_be_https / webhook_host_invalid / webhook_url_required / feishu_url_must_be_https / feishu_host_not_allowed / feishu_path_invalid / dingtalk_path_invalid / wecom_key_missing / slack_path_invalid | Bot URL malformed | Copy it verbatim from the bot settings |
smtp_host_required / smtp_port_out_of_range / smtp_port_not_int / smtp_security_invalid / smtp_from_invalid | Mail server configuration malformed | — |
recipients_required / recipient_invalid | Recipients empty or malformed | — |
unknown_channel / unknown_period / periods_not_array / hour_not_int / hour_out_of_range / severity_threshold_invalid | Schedule parameters invalid | — |
Settings and audit
| Code | Meaning |
|---|---|
masking_mode_unavailable | Invalid masking mode (params.choices) |
audit_webhook_url_invalid / audit_webhook_host_not_allowed / audit_webhook_host_refused | Audit forwarding target malformed / outside RST_AUDIT_WEBHOOK_ALLOWLIST / loopback or link-local |
audit_webhook_host_link_local | 169.254.169.254 is cloud instance metadata, not a SIEM |
syslog_url_invalid | Malformed syslog URL |
content_pack_rejected / content_pack_apply_failed / release_download_failed / release_download_server_error / no_release_to_download / rollback_failed / rollback_server_error | Content pack / online update signature, download or rollback failed |
body_not_json / body_empty / body_not_object / invalid_request / state_kind_unknown / name_required / title_empty / content_empty / markdown_empty / doc_id_required / panels_required / csv_text_missing | Request body malformed or required field missing |
content_token_required / import_failed / failed_case_not_found / persist_failed / save_failed / metrics_token_required | Content-pack token missing; import failed; eval case missing; write failed; /metrics token missing |