Troubleshooting by symptom

Resolve access, model, connector, OCR, workflow, voice, RPA and commerce problems using concrete checks and safe recovery steps.

Start with the smallest failing layer

Record the exact screen, timestamp, company, safe run reference and error code. Separate sign-in, permissions, model, knowledge, connector, workflow and provider issues. Changing all configuration at once makes the cause harder to find.

Symptom checklist

Symptom	First checks	Safe recovery
Cannot sign in	Correct deployment, email/invitation, expired session	Use password recovery or administrator identity support
Menu missing / `403`	Assigned role and route/tool scope	Have the owner grant the required permission; no shared admin login
Data missing after company switch	Selected company, resource ownership, binding	Return to authorized context and re-test; do not copy another company's IDs
Model credential missing	Provider/kind, tenant/company, model ID	Configure the correct credential and test a short task
Overload / rate limit	Provider incident, quota, concurrency	Bounded retry/backoff or approved model routing
Connector appears configured but fails	Upstream scope, secret binding, API contract, health age	Perform a bounded read test and correct configuration
Document upload fails	Supported type/limits, corruption, extractable text	Use the original supported file or a cleaner scan
OCR text is wrong	Orientation, language, scan quality, reading order	Compare against original; correct source or request manual review
Search has no result	Extraction/indexing, embedding availability, scope	Test a known phrase and the retrieval service separately
Workflow waits	Approval/event/wait step, worker availability	Review the waiting condition; do not bypass required approval
Workflow runs twice	Trigger/retry history, idempotency	Confirm external effects before retrying
Voice call has no reply	Callbacks, signature, mapped active agent, model	Inspect provider status and runtime health; no unsigned fallback
RPA times out	Target changes, session, selectors, approved domain	Pause schedules and revalidate the script in a test environment
Commerce answer is stale	Source sync, artifact TTL, revocation and merchant state	Refresh through the supported path; do not promise final inventory/price
Case decision refused	Current version, issuer configuration, distinct approvals	Resolve the exact reason and request a current decision

Distinguish refused, failed and unavailable

Refused means a boundary prevented the action. Failed means the attempted path did not complete. Unavailable can mean a provider capability is absent or a tenant feature is disabled. None should be turned into a fabricated success.

governed_cases_disabled is feature configuration; decision_service_not_configured is an issuer dependency; case_changed means existing decision evidence is no longer current. Do not edit an underlying record to bypass these conditions.

Reproduce safely

Use a synthetic record with the same role, company, source version and input shape. First verify the standalone provider/model/knowledge path, then the agent, then the workflow/channel. A successful admin test does not validate an operator's permissions.

If production customer data is required to diagnose the problem, use the organization's approved private evidence channel. Screenshots can contain sensitive fields; redact before sharing.

Escalate with useful evidence

Send expected versus actual behavior, reproduction steps, safe references, environment/version and attempted recovery. State whether a payment, email, account change or other external action may already have happened. Never send raw tokens or credentials.

When an external effect is ambiguous, pause and confirm with the system of record. A retry that makes the UI green but duplicates a customer action is not a fix.

View this page on AgenticOrg