Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/samkit511/SAW---Security-Analyst-Workspace/llms.txt

Use this file to discover all available pages before exploring further.

Most problems you encounter with SAW fall into one of two categories: environment setup issues that prevent the server from starting correctly, and runtime API errors that surface as non-2xx responses during normal operation. The sections below cover the most common cases with specific remediation steps for each.
If the dashboard loads and the API returns responses, but agent_summary is generic or workflow_status is DEGRADED with no real model output, the most likely cause is a missing or invalid Gemini API key.Check your environment file:Open .env and confirm that at least one of these variables is set to a valid key:
GOOGLE_API_KEY=your-key-here
# or
GEMINI_API_KEY=your-key-here
Verify quota:The key must have Gemini API quota enabled in Google Cloud. Visit the Google Cloud console and confirm the Gemini API is active for your project.Reinstall dependencies:If the key is correct but requests still fail, reinstall the Python packages to rule out a stale ADK installation:
pip install -r requirements.txt
After making changes, restart the server for the new environment variables to take effect.
On Windows, PowerShell’s default execution policy prevents running .ps1 scripts, including the venv activation script. You will see an error similar to:
.\.venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system.
Fix for the current session only:Run this before activating the environment. The Process scope means the policy change applies only to this PowerShell window and does not persist.
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
Do not set the execution policy at the LocalMachine or CurrentUser scope unless your organization’s security policy permits it. Use Process scope to keep the change temporary.
All /tasks, /assistant/request, /ingest-log, and /agent-test endpoints require the x-api-key header. A missing or incorrect value returns:
{
  "error": {
    "code": "unauthorized",
    "message": "Valid x-api-key header required."
  }
}
Verify the header is present:
curl -X GET http://127.0.0.1:8080/tasks \
  -H "x-api-key: demo"
Check the expected key value:The default key is demo. If you set the ASA_API_KEY environment variable, your requests must use that value instead. Confirm what the server loaded at startup by checking your .env file or the environment in which the server process is running.
SAW limits each source IP to 12 requests per 60-second window. When you exceed this limit the API responds with HTTP 429:
{
  "error": {
    "code": "rate_limited",
    "message": "Per-IP ingest rate limit exceeded.",
    "retry_after_seconds": 47
  }
}
Read the retry_after_seconds value and wait that many seconds before retrying. Do not immediately retry — repeated requests while rate-limited will not reset the window and will continue to return 429.
If you are running automated tests or load tests, add a delay between requests or use multiple source IPs to stay within the per-IP limit. You can also increase the limit for development by setting ASA_RATE_LIMIT_MAX_REQUESTS in your .env file.
If you send the same x-event-id value in two requests within 30 seconds, the second request returns HTTP 409:
{
  "error": {
    "code": "replay_detected",
    "message": "Duplicate event_id received within replay window.",
    "replay_window_seconds": 30
  }
}
Causes:
  • You are retrying a request that already succeeded and reusing the same event ID.
  • Your log forwarder is sending duplicate events with identical IDs.
Fix:Generate a new, unique x-event-id value for each distinct log event. If you need to retry a failed request, verify first that the original did not succeed by checking /latest or the incident ID. If the original succeeded, do not retry with the same event ID.Wait the full 30-second replay window before reusing an event ID if you have no other option.
SAW limits concurrently in-flight requests to prevent resource exhaustion. When the limit is reached, new requests return HTTP 503:
{
  "error": {
    "code": "overloaded",
    "message": "Too many in-flight requests.",
    "retry_after_seconds": 1
  }
}
Wait one second and retry. The default maximum is 8 concurrent in-flight requests. For high-throughput environments, increase this limit by setting ASA_MAX_INFLIGHT in your environment:
ASA_MAX_INFLIGHT=16
Monitor the current in-flight count without authentication via the /metrics-json endpoint:
curl http://127.0.0.1:8080/metrics-json
DEGRADED means the pipeline completed but at least one agent encountered an error and did not produce its normal output. The system continues rather than failing entirely.Check which agents failed:Look at trace.agent_orchestration.failures in the response:
{
  "workflow_status": "DEGRADED",
  "trace": {
    "agent_orchestration": {
      "failures": [
        {
          "agent": "RiskAgent",
          "reason": "Model returned empty response."
        }
      ]
    }
  }
}
The meta.resilience.failed_agents count also gives you a quick summary of how many agents did not complete successfully.Common causes:
  • A Gemini model quota error mid-pipeline — verify your API key and quota as described in the first accordion above.
  • The ASA_ENABLE_ADK_ADVISORY or ASA_ENABLE_ESCALATION feature flags are set to false, causing those pipeline stages to be skipped. This is expected behavior, not an error.
  • A transient network issue reaching the Gemini API. Retry the request; most transient failures resolve on the next attempt.

Build docs developers (and LLMs) love

Get started for freeTalk to us