AI Agent Troubleshooting, Error Codes & Operational FAQ

Comprehensive diagnostic guide and resolution matrix for AI agent execution failures, rate limiting, and tool calling exceptions.

1. Overview & Business Value#

This reference document covers common error codes, diagnostic procedures, and resolution steps for the SmartERP Autonomous AI Fleet.

1. Diagnostic Error Matrix#

Error Code	Error Description	Root Cause	Resolution Procedure
`ERR-AI-429`	Upstream Rate Limit Exceeded	All provider API keys exhausted quota.	Check key pool health; verify multi-key rotation settings in AI Providers.
`ERR-AI-401`	Unauthorized / Invalid Key	Model API key revoked or expired.	Update API credentials in Settings → Ashewa AI.
`ERR-AI-TOOL-01`	Tool Execution Exception	ORM constraint violation during tool call.	Check user security group permissions for the underlying model.
`ERR-AI-PARSE-02`	Output Schema Mismatch	Model returned unstructured text instead of JSON schema.	Lower temperature parameter to 0.1 and re-test.
`ERR-AI-STG-LOCK`	Staging Queue Concurrency Lock	Two approvers attempting simultaneous action.	Wait 30 seconds for lock release or force-release via admin console.

2. Frequently Asked Questions (FAQ)#

Can agents modify records without human approval?#

Only Tier 3 and Tier 4 agents operating within explicitly defined monetary and operational thresholds can auto-commit transactions. All financial postings and high-impact changes require Tier 2 HITL staging approval.

How is data privacy maintained with cloud models?#

SmartERP includes a built-in PII redaction proxy that masks sensitive personal identifiers, bank account numbers, and salaries before sending prompts to external model providers.

2. Prerequisites & Security Access Groups#

Required Modules: muk_ai, muk_mcp, smarterp_ai_suite
Security Group: Ashewa AI / User (Technical ID: muk_ai.group_ai_user)
Master Data Dependencies: Configured AI provider credentials, active system prompts, and departmental cost centers.

3. Step-by-Step UI Execution & Verification#

Step 1: Navigating to the Operational Interface#

Log into your SmartERP instance at https://smarterp.et/odoo.
Open the main App Switcher and select Ashewa AI.
Select the operational workspace corresponding to this agent suite.

{screenshot:90-troubleshooting-and-agent-faq-step1-navigation}

Step 2: Executing Agent Actions#

Review agent prompts and execution parameters.
Trigger the scheduled or on-demand workflow action.
Validate output in the generated operational log.

{screenshot:90-troubleshooting-and-agent-faq-step2-execution}

4. Advanced Configuration Points#

Scheduled Crons: muk_ai.ir_cron_agent_health_check runs every 30 minutes.
Multi-Company Isolation: Multi-company record rules ensure agent context is isolated to Company 1 (Ashewa Technology Solutions S.C.).

5. Comprehensive Troubleshooting Matrix#

Symptom / Error	Probable Root Cause	Resolution Action
`Agent unresponsive or timeout`	Network latency or API endpoint outage.	Verify provider connection in Settings → AI Providers.
`Access Denied during agent execution`	User lacks assigned operational permissions.	Assign user to the designated operational group.

መጨረሻ የተሻሻለው: 2026-10-30