Troubleshooting
Error codes
Every error the gateway returns carries a code. All codes with their meaning and remedy, by area.
A gateway error response is {"detail": "<message>", "code": "<code>", "params": {...}}. The UI shows the message in the current language, API clients branch on code, and params fills in the message.
| Code | Meaning | Remedy |
|---|
login_required | Not signed in, or the session expired | Sign in again |
sso_identity_required | SSO is on, but the request has no verified identity | Sign in through the SSO entry point; check oauth2-proxy |
read_only | A read-only role cannot make changes | Ask an administrator |
admin_role_required | The current role (params.role) has no admin rights | Ask an administrator |
admin_group_required | The SSO account is not in an RST_RBAC_ADMIN_GROUPS group | Ask the IdP administrator |
admin_session_or_token_required | Admin endpoints need a valid session or RST_ADMIN_TOKEN | Sign in again, or send the token in the X-RST-Admin-Token header |
admin_login_required | Admin actions require signing in | Sign in |
metrics_token_required | Scraping /metrics needs a token | Send RST_METRICS_TOKEN in the X-RST-Metrics-Token header (or Authorization: Bearer) |
csrf_rejected | Cross-site request refused; origin check failed | Act from the product's own pages |
rate_limited | Rate limit hit | Wait params.seconds; raise RST_RATELIMIT_* for large teams |
| Code | Meaning | Remedy |
|---|
bad_credentials | Wrong username or password | None |
login_throttled | Too many failed sign-ins | Retry in 5 minutes |
default_password_refused | Still on the shipped password; remote sign-in refused | Set RST_ADMIN_PASSWORD_HASH and restart; a LAN lab may set RST_ALLOW_DEFAULT_PASSWORD=1 |
password_login_disabled | Password login is not enabled | Sign in through SSO |
password_change_not_supported | Only password-login accounts can change their password here | Change it in the identity provider |
password_in_env_only | On a single-account deployment the password is in RST_ADMIN_PASSWORD_HASH | Put a new hash in .env and restart |
current_password_wrong | The current password is wrong | None |
password_too_short, password_min_length | Under 8 characters | None |
user_db_not_configured | No user table, so multiple accounts cannot be managed | Set RST_USER_DB_URL |
username_required, user_exists, user_not_found | Account name empty, taken, or unknown | None |
unknown_role | Role not among params.choices | None |
last_admin_locked, last_admin_undeletable | The last enabled administrator cannot be disabled, demoted, or deleted | Create another administrator first |
cannot_disable_self, cannot_delete_self | You cannot disable or delete your own account | Ask another administrator |
| Code | Meaning | Remedy |
|---|
feature_needs_standard | params.feature needs Professional or higher | Activate a license |
incident_report_needs_standard | Incident reports need Professional or higher | Activate a license |
platform_checkup_needs_standard | The platform checkup needs Professional or higher | Activate a license |
feature_sealed | No license on this host, or the license lacks the feature, so the feature stays locked | Activate a license that includes it on the License page |
reports_need_professional | Reports need Professional or higher | Activate a license |
users_need_professional | Community allows 1 user | Activate a Professional or Enterprise license |
user_seats_exhausted | Enabled accounts have reached the users in the license (params.seats) | Disable an account, or buy more users |
license_invalid | Signature, decryption, or tamper check failed | Ask sales to re-issue |
license_expired | Expired past the 7-day grace period; service locked | Renew |
license_revoked | The license was revoked | Contact sales |
license_heartbeat_lost | No heartbeat for 7 days; service locked | Check network access to the license server |
license_status_abnormal | The license is in an unexpected state | Contact support |
machine_id_unreadable | Hardware identity unreadable (params.reason) | Check the /etc/machine-id mount |
license_activate_failed | Activation refused (params.reason: seats used up, fingerprint mismatch, wrong product, and so on) | Act on the reason |
license_activate_error, license_deactivate_error | Activation or deactivation failed (params.reason) | Act on the reason |
| Code | Meaning | Remedy |
|---|
es_unreachable | Cannot reach Elasticsearch | Check ES_URL, the network, and the certificate |
es_auth_failed | Elasticsearch authentication failed | Check ES_USER and ES_PASSWORD, or ES_API_KEY |
es_forbidden | The account cannot access this index | Add privileges to the Elasticsearch role |
es_index_not_found | The index does not exist | Check the index or alias name, and whether it was rolled over and deleted |
es_timeout | Elasticsearch query timed out | Narrow the time range or size; adjust RST_ES_TIMEOUT_S (default 30 s) |
es_request_failed | Other Elasticsearch error (params.reason) | Act on the reason |
es_audit_query_failed, es_resolve_index_failed | Audit query or index resolution failed (params.reason) | Act on the reason |
index_not_whitelisted | Index outside RST_INDEX_WHITELIST (params.patterns) | Add the pattern under Index allowlist in Settings |
index_is_internal | The index is the product's own storage, not a query target | Use the matching page |
no_queryable_index | Nothing to query | Check the data source connection or widen the allowlist |
dsl_validation_failed | The query failed read-only validation (params.reason) | Change the query |
nothing_to_explain | The result has neither aggregations nor samples | None |
| Code | Meaning | Remedy |
|---|
llm_generation_failed | Model generation failed (params.reason) | Check the provider in AI settings |
llm_timeout | Model call timed out | Raise the provider timeout to 90 s or more; lower the clusters sent to the model from the default 30 to 10 |
llm_first_token_timeout | No answer started within params.limit_s seconds; stopped | Rephrase and retry, or lower the reasoning level |
providers_empty | The provider list is empty | Configure at least one |
model_required | No model given | None |
connection_test_failed | Connection test failed (params.reason) | Act on the reason |
embedding_not_configured | No embedding model | Configure one under the knowledge-base embedding model in AI settings |
kb_dims_mismatch, kb_dim_mismatch | The .rst_copilot_kb dimension differs from the current embedding model | Switch back, or delete .rst_copilot_kb and upload the documents again |
kb_upload_failed, kb_list_failed, kb_search_failed, kb_delete_failed | Knowledge-base upload, listing, search, or delete failed | Read the gateway log |
| Code | Meaning |
|---|
investigation_failed, triage_failed, detection_rule_failed, report_generation_failed, incident_report_failed, platform_checkup_failed, alerts_aggregate_failed | That feature failed; params.reason has the detail |
field_dict_failed, explain_log_failed, explain_result_failed, suggest_angles_failed | Field dictionary, log explanation, result explanation, or follow-up angle generation failed |
detection_rule_rejected | The detection rule was rejected (params.reason) |
too_many_alerts | At most params.cap alerts per triage run |
alerts_or_index_required | Triage needs either alerts or index |
incident_input_required | An incident report needs alert, alert_id, or investigation |
conversation_not_found, analysis_record_not_found | Conversation or analysis record missing or expired |
failed_case_not_found | No such failed case |
kibana_link_failed, kibana_data_view_not_found | Kibana deep link failed; Kibana has no data view for this index, or the gateway account lacks the Kibana Discover privilege (see Elasticsearch account permissions) |
feedback_persist_failed, save_failed, persist_failed | Feedback or data could not be written (params.reason) |
| Code | Meaning | Remedy |
|---|
alert_webhook_disabled | Alert webhook push is off | Set RST_ALERT_WEBHOOK_SECRET |
alert_webhook_token_invalid | Wrong X-RST-Alert-Token | Check the Kibana connector header |
alert_not_found, notify_target_not_found | No such alert or destination | None |
push_failed | Delivery failed (params.reason) | Read the delivery log |
delivery_not_retryable | Cannot resend (missing, or still queued or sending) | None |
webhook_url_required, webhook_must_be_https, webhook_host_invalid, dingtalk_path_invalid, feishu_url_must_be_https, feishu_host_not_allowed, feishu_path_invalid, slack_path_invalid, wecom_key_missing | Bot webhook URL empty or malformed | Copy it verbatim from the bot settings |
smtp_host_required, smtp_port_not_int, smtp_port_out_of_range, smtp_security_invalid, smtp_from_invalid | Mail server settings invalid; the port must be an integer from 1 to 65535 | None |
recipients_required, recipient_invalid | Recipients empty or malformed | None |
| Code | Meaning |
|---|
start_after_end | start must be earlier than end |
periods_not_array, unknown_period | Periods must be an array of allowed values |
name_required | Name is empty |
unknown_channel | Channel not among the allowed values |
severity_threshold_invalid | Invalid alert severity threshold |
hour_not_int, hour_out_of_range | The send hour must be an integer from 0 to 23 |
| Code | Meaning |
|---|
masking_mode_unavailable | Invalid masking mode (params.choices) |
es_url_not_string, es_url_invalid | The Elasticsearch URL is not a full http:// or https:// URL |
syslog_url_invalid | Invalid syslog URL (supported schemes in params.schemes) |
audit_webhook_url_invalid | The audit forwarding URL is not a full http:// or https:// URL |
audit_webhook_host_not_allowed | Forwarding target not in RST_AUDIT_WEBHOOK_ALLOWLIST |
audit_webhook_host_refused, audit_webhook_host_link_local | Forwarding cannot target this host, including loopback and link-local addresses (169.254.169.254 is cloud instance metadata, not a SIEM) |
| Code | Meaning |
|---|
content_pack_rejected | Content pack failed signature, version, or compatibility checks (params.reason) |
content_pack_apply_failed | Server error while applying the content pack |
no_release_to_download | No new release to download |
release_download_failed, release_download_server_error | Release download or staging failed |
rollback_failed, rollback_server_error | Rollback failed |
import_failed, csv_import_failed, csv_text_missing | Import failed, or the request has no CSV text |
| Code | Meaning |
|---|
rule_id_invalid | Rule ID must be 3 to 64 letters, digits, or . _ - |
rule_title_required | Rule title is empty |
rule_query_required | The collection query (osquery SQL) is empty |
rule_judge_missing | The judge is missing |
rule_needs_field, rule_needs_expected | This operator needs a judge field or expected value |
rule_eol_needs_query | The eol operator needs a query that collects the OS version |
rule_operator_invalid, rule_severity_invalid | Invalid operator or severity |
rule_shape_invalid, body_not_object | Invalid rule structure, or the body is not a JSON object |
baseline_rule_not_found | Rule missing, or delete failed |
These codes mean the API request itself is incomplete or out of range. They do not normally appear when you work in the UI.
| Code | Meaning |
|---|
body_empty, body_not_json | Request body empty or not valid JSON |
doc_empty, dsl_empty, alert_empty, investigation_empty, cluster_empty, markdown_empty, question_empty, query_empty, title_empty, content_empty | That field is empty |
index_required, doc_id_required, panels_required, content_token_required | A required field is missing |
alerts_not_list | alerts must be an array |
size_out_of_range, limit_out_of_range, top_k_out_of_range | Out of range: 1 to 500, 1 to 200, and 1 to 50 respectively |
offset_negative | offset cannot be negative |
state_kind_unknown | Unknown state type |
invalid_time | Invalid time value |
invalid_request | Other request error (params.reason) |
