Troubleshooting
Find the fastest path to a fix when something in Jutsu does not behave as expected. This hub groups the most common problems by area; each table maps a symptom to its likely cause and the action that resolves it, with links to the in-depth page for that area.
Ingestion
No events or alerts are reaching Jutsu, or they stopped arriving. Most ingestion problems come down to the forwarder, the ingest key, or the endpoint.
| Symptom | Likely cause | Fix |
|---|---|---|
| No new events or alerts appear at all | The forwarder or connector is not running | Confirm your Wazuh integration, syslog forwarder, or connector is up and shipping data. See Wazuh data source. |
Requests are rejected with 401 | The ingest API key is missing, invalid, expired, or inactive | Verify the key is active and sent in the X-API-Key header. See Ingestion API. |
| Some events index, others are dropped | Per-item payload validation failed on a batch | Read the validationErrors array in the response, fix the bad entries, and resend. See Ingestion API. |
| Events go nowhere with no error in Jutsu | Forwarder points at the wrong webhook endpoint | Confirm the forwarder targets the correct ingest webhook URL (Wazuh vs. syslog). See Ingestion API. |
Credentials
An AgentSOAR provider credential fails to validate or stops working. Validation almost always points to a secret, a permission, or a missing consent.
| Symptom | Likely cause | Fix |
|---|---|---|
| Credential validation fails on connect | Wrong client secret, key, or token | Re-enter the secret from the provider and revalidate. See Credentials & domains. |
| Validation passes but actions are denied | The credential lacks the required scopes or roles | Grant the permissions the connector needs on the provider side. See the connector page, e.g. Microsoft 365. |
| Microsoft consent error during setup | Admin consent was never granted for the app | Have a tenant admin approve admin consent, then revalidate. See Microsoft 365. |
| A working credential suddenly fails | The secret rotated or expired | Re-authenticate the credential. See Credentials & domains. |
Response actions
An AgentSOAR action fails, or you need to undo one. Every execution records a status and, on failure, a reason that isolates the cause.
| Symptom | Likely cause | Fix |
|---|---|---|
Execution failed with credential_invalid | The provider credential was rejected | Rotate or re-authenticate the credential, then re-run. See Executions & revert. |
Execution failed with cloud_api_error | The provider's API returned an error | Check provider-side status and limits, then retry the action. See Executions & revert. |
Execution failed with inventory_not_found | The target host or user could not be resolved | Confirm the asset exists in inventory and the identifier is correct. See Executions & revert. |
Execution failed with input_invalid | The action inputs failed validation | Correct the inputs (IP, email, domain, reason) and re-run. See Executions & revert. |
A run is stuck awaiting_reauth | The credential is invalid or expired mid-run | Re-authenticate within the cutoff window before it becomes expired_awaiting_reauth. See Credentials & domains. |
| Revert did not restore the change | The action was not revertible, or revert_failed | Retry the revert; note AWS isolate is not revertible once the host was already isolated. See Executions & revert. |
Ingest API errors
A request to the ingest API returns an error status. The status code tells you whether the problem is the API key, access, or a rate limit.
| Symptom | Likely cause | Fix |
|---|---|---|
401 Unauthorized | The ingest API key is missing, invalid, expired, or inactive | Send a valid, active ingest API key in the X-API-Key header. See Ingestion API. |
403 Forbidden | The credential is valid but lacks access to the resource | Use an account or key with the right access for the action. See Role-based access control. |
429 Too Many Requests | A rate limit was exceeded | Back off and retry, respecting the rate-limit response headers. |
Not every status applies to every endpoint. Treat these as the general model and confirm per-endpoint behavior against your deployment.
Still stuck?
If an issue is account-specific or you cannot resolve it from these tables, contact your Jutsu administrator or book a call. See Support for all the ways to get help.