🔧 Error Troubleshooting FAQ
⚠️ Network is the root cause of 80% of problems — API can't connect, Git can't pull, plugins can't install, it's most likely a network issue. When encountering any error, first check if you can access the external network (
curl -I https://www.baidu.com), if not, switch networks / enable proxy.
Troubleshooting is now split into the topic pages below. Start with "Browse by Topic" to find the right page; when the log already contains a specific error code or keyword, use the "⚡ Error Code Quick Reference" to jump straight there; if you're unsure which category your problem falls into, check the "📋 Error Troubleshooting Flowchart" at the end.
Browse by Topic
Startup and Access Troubleshooting — MaiBot won't start, or the WebUI won't open or won't accept your login: configuration files, MCP, ports, WebUI access and login, and Git operations in the WebUI.
Model and Rule Troubleshooting — Unexpected bot behavior: API keys and balance, network timeouts, regular expressions, and keyword rules.
Runtime and Data Troubleshooting — Runtime anomalies and data problems: missing replies, databases, emojis, memory, disk space, and person or user data.
Plugin and Adapter Troubleshooting — Plugins and adapters: plugin loading failures, adapters that are not connected or whose accounts are unavailable, and WebSocket reconnect loops.
Getting Help — Self-checks before asking, the issue checklist, community support channels, and how to export logs.
⚡ Error Code Quick Reference
Quickly locate the corresponding scenario by common keywords in error logs.
HTTP Status Code Quick Reference
HTTP 400 Bad Request 🟧 Severe → Adapter Not Connected or Account Unavailable — Request parameter error, message sending failed
HTTP 401 Unauthorized 🟥 Fatal → API Key Error / Insufficient Balance — API Key invalid or missing
HTTP 401 Unauthorized 🟧 Severe → WebUI Login Failed / Token Expired — Session expired or Token invalid
HTTP 402 Payment Required 🟧 Severe → API Key Error / Insufficient Balance — Account balance insufficient
HTTP 403 Forbidden 🟥 Fatal → API Key Error / Insufficient Balance — API Key insufficient permissions
HTTP 429 Too Many Requests 🟧 Severe → Network Timeout / Connection Failure — Request frequency too high, rate limited
HTTP 500 Internal Server Error 🟧 Severe → Network Timeout / Connection Failure — API server internal error
HTTP 502 Bad Gateway 🟧 Severe → Network Timeout / Connection Failure — Gateway error, upstream service unreachable
HTTP 503 Service Unavailable 🟧 Severe → Network Timeout / Connection Failure — Service temporarily unavailable (overload/maintenance)
Common Error Keyword Index
Address already in use / [Errno 98] / [Errno 10048] 🟧 Severe → Port Occupied — Port is already in use by another process
APIConnectionError 🟧 Severe → Network Timeout / Connection Failure — API connection failed
Connection refused / 无法访问此网站 🟥 Fatal → WebUI Page Won't Open — WebUI service not started or port unreachable
database is locked 🟧 Severe → Database Error — Database locked by multiple processes
DatabaseError / OperationalError 🟧 Severe → Database Error — Database operation exception
FileNotFoundError 🟥 Fatal → Configuration File Not Found or Incorrect Format — Configuration file does not exist
Host version incompatible / SDK version incompatible 🟧 Severe → Plugin Loading Failed — The plugin's declared version range does not cover the current version
ImportError / ModuleNotFoundError 🟧 Severe → Plugin Loading Failed — Plugin dependency missing
No space left on device 🟧 Severe → Log Files Too Large / Disk Space Full — Disk space insufficient
PluginConfigVersionError 🟧 Severe → Plugin Loading Failed — Plugin configuration version not supported
re.error / bad escape 🟨 Warning → Invalid Regular Expression — Regex syntax error
TimeoutError 🟧 Severe → Network Timeout / Connection Failure — Request timeout
Token expired 🟨 Warning → WebUI Login Failed / Token Expired — Login session expired
TOML syntax error 🟥 Fatal → Configuration File Not Found or Incorrect Format — Configuration file format error
ValueError 🟥 Fatal → MCP Configuration Error — MCP server configuration parameter invalid
Emoji registration failed 🟨 Warning → Emoji System Error — Quantity limit exceeded or data/emojis/ is unwritable
Memory loading failed 🟧 Severe → Memory System Error — Memory index corrupted or memory directory unwritable
Session 过期 🟨 Warning → WebUI Login Failed / Token Expired — Browser session expired
📋 Error Troubleshooting Flowchart
Not sure which category your problem falls into? Follow the flowchart to find the corresponding section.