# Troubleshooting Solutions for common issues organized by feature area. Before diving into specific symptoms below, consider the proactive tools Seclai provides for diagnosing and preventing problems. --- ## Proactive Debugging Seclai has several built-in tools that help you diagnose issues faster and catch problems before they reach users. ### Inspect Agent Traces Every agent run produces a detailed trace showing each step's input, output, duration, and status. When a run fails or produces unexpected results, the trace is the fastest path to the root cause. - Open any run from the **Traces** tab on the agent detail page. - Expand individual steps to see the exact prompt sent, the model's response, tool calls, and any errors. - Traces include pseudo-steps for governance evaluations, prompt scans, and agent evaluations — so you can see exactly where content was flagged or blocked. See [Agent Traces](https://seclai.com/docs/agent-traces) for the full guide. ### Test Changes with Past Runs After modifying an agent's prompts, model, or step configuration, you can re-run a previous agent run to compare results. This lets you validate changes against real-world inputs without waiting for new triggers. - From the **Traces** tab, open a past run and click **Re-run** to execute the agent with the same input but your updated configuration. - Compare the new trace side-by-side with the original to see how your changes affected the output. This is especially useful for debugging prompt regressions or verifying that a model swap produces comparable results. ### Set Up Alerts Alerts notify you when something goes wrong — before users report it. Configure alerts on agents to catch failures, unexpected outputs, or performance issues early. - **Run failure alerts** — Get notified when an agent run fails so you can investigate immediately. - **Model lifecycle alerts** — Get warned when a model you depend on is deprecated or approaching sunset. See [Model Lifecycle](https://seclai.com/docs/model-lifecycle). - **Credit alerts** — Get notified when your account credits are running low. Configure alerts from the **Alerts** tab on the agent detail page, or manage account-wide alert preferences in Settings. See [Alerts](https://seclai.com/docs/alerts) for setup details. ### Use Agent Evaluations Agent evaluations let you automatically assess the quality of agent outputs using LLM-based criteria. Rather than manually reviewing every run, define evaluation criteria and let Seclai score outputs for you. - **Eval and retry** — Evaluate every run and automatically retry the step if the output fails the criteria. Good for production agents where output quality is critical. - **Sample and flag** — Evaluate a random sample of runs and flag low-scoring outputs for human review. Good for monitoring agents at scale without evaluating every run. - **Output expectation** — Define expected output patterns for manual spot-checking. Evaluations appear in agent traces as pseudo-steps, so you can see scores and feedback inline with the run. See [Agent Evaluations](https://seclai.com/docs/agent-evaluations) for the full guide. ### Use Governance Policies Governance policies screen content flowing through your agents and sources against safety and quality rules. They can flag content for human review or block it from reaching users. - **Blocking policies** gate the pipeline — content that violates the policy is held until reviewed or rejected outright. - **Non-blocking policies** run in the background as audits, flagging violations without interrupting the flow. - **Test policies** against real content samples before enabling them in production to calibrate thresholds and reduce false positives. Governance evaluations appear in agent traces and in the Governance → Review queue, giving you full visibility into what was screened and why. See [Governance](https://seclai.com/docs/governance) for the full guide. --- ## Content Sources ### Content Not Indexing - **Check URL accessibility** — Verify the RSS feed or website URL is publicly accessible. Sites behind paywalls, logins, or IP restrictions will fail. - **Review the Pulls tab** — Open the source detail page → Pulls tab to see recent pull statuses and error messages. A red badge means every URL failed; yellow means partial success. See [Content Sources → Pull Status](https://seclai.com/docs/content-sources#pull-status-and-errors) for details. - **Validate feed format** — For RSS feeds, the feed must be valid XML. Paste the URL into a browser to verify it returns RSS/Atom content. - **Check polling schedule** — Sources set to "manually" won't poll automatically. Switch to daily or hourly, or trigger a manual pull. - **Check the content filter** — An aggressive content filter (e.g. `ai_main_content_skip_ads`) may strip all visible text from some pages. ### Source Not Polling - **Polling set to "manually"** — Switch to a scheduled frequency (hourly, daily, weekly). - **Source in error state** — If recent pulls failed repeatedly, the source may need its URL or configuration corrected. - **Account subscription** — Polling requires an active subscription. Check Settings → Billing. ### File Upload Failures - **"This file could not be converted"** — The file format is unsupported or the file is corrupted. Re-save as PDF, DOCX, or another [supported format](https://seclai.com/docs/content-sources#content-store). - **"No text could be extracted"** — The file has no machine-readable text (e.g. scanned-image PDF without OCR). Re-export with OCR enabled. - **Legacy `.doc` files** — Word 97–2003 binary `.doc` is not supported. Open in Word, Google Docs, or LibreOffice, save as `.docx`, and re-upload. - **File too large** — Individual files must be under 200 MB. ### Website Crawl Not Finding Pages - **Crawl depth too shallow** — Increase `crawl_depth` (max 5). - **URL filters too restrictive** — Review include/exclude regex patterns. - **No sitemap** — Enable sitemap crawling if the site has a `sitemap.xml`. - **`robots.txt` blocking** — Check that the site's `robots.txt` doesn't disallow the crawler. - **Crawl limit reached** — Increase `crawl_limit` if the site has more pages than the limit. --- ## Agents ### Poor Agent Responses - **Insufficient content** — Index at least 10–20 pieces of content for reliable retrieval results. - **Vague system prompt** — Be specific about the agent's role, audience, and output format. See [Prompt Best Practices](https://seclai.com/docs/prompt-best-practices). - **Wrong knowledge base** — Verify the correct knowledge base is connected in the Retrieval step. - **Model mismatch** — Some tasks need stronger models. Try a more capable model or adjust temperature. See [Models](https://seclai.com/docs/models). - **Source quality** — Low-quality, outdated, or irrelevant sources produce poor retrieval results. Review and prune content. ### Agent Not Triggering - **Trigger disabled** — Check the agent's trigger configuration. Schedule-based triggers need an active schedule; content triggers need an active source that's producing content. - **No new content** — Content triggers (`content_added`, `content_updated`) only fire when content actually changes. If the source hasn't polled or found new items, the agent won't run. - **Credits exhausted** — Agents won't run if the account has no remaining credits. Check Settings → Credits & Usage. - **Agent disabled** — Verify the agent is enabled (not paused or archived). ### Streaming Not Working - **Wrong result step** — Use a **Streaming Result** step instead of Display Result. Only Streaming Result supports real-time SSE output. - **Governance blocking** — If governance policies with `blocking: true` are active, output is held until evaluation completes, which disables streaming. Use non-blocking policies if real-time streaming is required. - **Priority queue** — Agents triggered via the priority queue may not stream. Chat and API-triggered runs with `stream: true` support streaming. - See the [Agent Streaming](https://seclai.com/docs/agent-streaming) guide for the full protocol. ### Agent Run Shows "Failed" - **Check the trace** — Open the failed run from the Traces tab. The failed step shows the error message and stack trace. See [Agent Traces](https://seclai.com/docs/agent-traces). - **External API errors** — Webhook Call and Web Fetch steps can fail if the external API returns an error or times out. - **Model rate limits** — If many agents run simultaneously, LLM providers may rate-limit requests. Reduce concurrency or switch models. - **Step timeout** — Long-running steps may time out. Simplify the prompt or split into smaller steps. --- ## Governance ### No Evaluations Appearing - **Governance not enabled** — Verify governance is turned on in Settings → Governance. The master switch must be enabled. - **No active policies** — At least one policy must be enabled. Check the Policies tab. - **Wrong screening points** — Each policy has `review_input` and `review_output` flags. Verify the relevant flag is enabled for your use case. - **No content flowing** — Evaluations only appear when content passes through a screening point (agent run, source content ingestion, etc.). ### Too Many False Positives - **Raise the flag threshold** — Increase the flag threshold on the triggering policy (e.g. from 0.5 to 0.7). Lower values are stricter. - **Refine policy text** — Add clarifying examples of what is and isn't a violation. - **Switch evaluation tier** — The `FAST` tier trades accuracy for speed. Try `BALANCED` or `THOROUGH` for more nuanced evaluations. - **Use the Test tab** — Test your policy against real content samples to calibrate thresholds before enabling in production. ### Content Not Being Blocked - **Block threshold too high** — Lower the block threshold so more violations are caught. - **Policy not set to blocking** — Non-blocking policies run as fire-and-forget audits. Set `blocking: true` to gate the pipeline. - **Policy scoping** — Verify the policy is scoped to the correct agent, step, or source. ### Test Tab Disabled - The Test tab requires at least one **enabled** policy in the account. Create or enable a policy first. --- ## API & Authentication ### 401 Unauthorized - **Missing or invalid API key** — Include the `X-API-Key` header with a valid key. Keys are managed in Settings → API Keys. - **Expired OAuth token** — If using Bearer authentication, refresh your Cognito access token. - **Wrong endpoint** — Public API endpoints start with `/api/`. Authenticated endpoints start with `/authenticated/`. ### 403 Forbidden - **Wrong account** — The API key belongs to a different account than the resource you're accessing. - **Resource not shared** — The resource (agent, knowledge base, etc.) is not shared with your account or organization. - **Insufficient permissions** — Some operations require owner-level access. ### Rate Limiting (429) - API requests are rate-limited per account. If you receive a 429 response, back off and retry with exponential delay. - See [API Introduction](https://seclai.com/docs/api-introduction) for rate limit details. ### MCP Connection Issues - **Server not connecting** — Verify the MCP server URL and API key in your client configuration. See [MCP Server](https://seclai.com/docs/mcp). - **Tools not appearing** — Ensure your MCP client supports the tools protocol. Restart the client after configuration changes. --- ## Credits & Billing ### Credits Depleting Quickly - **High-frequency polling** — Hourly polling of large sources generates many embedding credits. Switch to daily or weekly. - **Large embedding dimensions** — Higher dimensions cost more per chunk. Use smaller dimensions for cost-sensitive workloads. - **Expensive models** — Some LLM models cost more credits per call. Check model pricing in [Models](https://seclai.com/docs/models). - **Governance overhead** — Each governance evaluation consumes credits. Use the `FAST` tier for lower costs, or limit blocking policies to critical agents. - See [Credits & Usage](https://seclai.com/docs/credits-usage) for the full breakdown. ### No Credits Remaining - Agents, governance evaluations, and content polling stop when credits run out. - Purchase additional credits in Settings → Credits & Usage, or wait for your next billing cycle renewal. - Content already indexed remains searchable — only new processing stops. --- ## Knowledge Bases ### Poor Search Results - **Too few sources** — Add more content sources to improve coverage. - **Mismatched embedding models** — Use the same embedding model across all sources in a knowledge base for consistent retrieval. - **Chunk size too large** — Smaller chunks (500–1000 chars) improve precision for specific queries. Larger chunks (2000–3000 chars) retain more context. - **Try reranking** — Enable reranking in the Retrieval step to improve result ordering. ### Knowledge Base Chat Not Answering - **No content indexed** — Check that at least one source has completed polling and indexing. - **Content still processing** — New sources take time to fetch, transcribe, and embed. Check the source's progress indicator. - **Question outside scope** — The chat can only answer questions based on indexed content. If the content doesn't cover the topic, the chat will say so. --- ## Getting Help If you can't resolve an issue: - **Check the [FAQ](https://seclai.com/docs/faq)** — Answers to frequently asked questions. - **API docs** — See the [API Reference](https://seclai.com/docs/api) for endpoint details. - **Contact support** — Reach out through the in-app feedback button or email support.