🔧 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.

Listed in order of error frequency from highest to lowest. New users should prioritize the 🔴 Extremely High Frequency section. If you're unsure which category your problem falls into, first check the "📋 Error Troubleshooting Flowchart" at the end.

🔴 Extremely High Frequency Errors (Inevitable for New Users)

Covers scenarios 1–6, the most common problems encountered by new users when deploying and using MaiBot for the first time.

Scenario 1: Configuration File Not Found or Incorrect Format

Error Symptoms

MaiBot crashes immediately on startup
Terminal prints TOML parsing error, e.g. Invalid TOML syntax
Or prompts FileNotFoundError: config/bot_config.toml
Or prompts API密钥不能为空，请在配置中设置有效的API密钥。
Or prompts API基础URL不能为空

Quick Self-Check Trio

1️⃣ Does the configuration file exist? Check if bot_config.toml exists in config/ 2️⃣ Is the TOML syntax correct? Strings need quotes, numbers don't, booleans are lowercase 3️⃣ Have you used WebUI to modify it? WebUI automatically validates syntax and won't make errors

Solutions

Method 1 (Recommended): Modify Configuration via WebUI WebUI automatically creates and validates configuration without manually writing TOML, no errors:

Start MaiBot, open browser and visit http://localhost:8001
Go to the "Configuration Management" page
Fill in the content as prompted on the page and save

If MaiBot cannot start due to configuration errors, you can fix the critical errors to get the program running first, then adjust settings through WebUI.

Method 2: Manually Copy Example Files If WebUI is temporarily unavailable, copy the example files as a starting point:

bash

cp config/bot_config.example.toml config/bot_config.toml
cp config/model_config.example.toml config/model_config.toml

Method 3: Check TOML Syntax (Reference for Manual Editing)

toml

# ✅ Correct examples
[bot]
nickname = "麦麦"           # Strings need quotes
port = 8001                 # Numbers don't need quotes
enabled = true              # Booleans are lowercase

# ❌ Incorrect examples
[bot]
nickname = 麦麦             # Error! No quotes
port = "8001"              # Error! Numbers shouldn't have quotes
enabled = True             # Error! Should be lowercase true

Method 4: Online Validation If you've manually edited the file and aren't sure about the format, use an online TOML validator to check.

Prevention Tips

📝 Use WebUI to modify configuration — WebUI automatically validates syntax, no errors
💾 Backup before modifying — cp bot_config.toml bot_config.toml.bak
🔍 Make small changes — Only modify a few lines at a time, test if startup works after saving

Scenario 2: API Key Error / Insufficient Balance

Error Symptoms

Bot completely unresponsive
Backend log shows 401 Unauthorized / 402 Payment Required / 403 Forbidden
Log prompts API key is invalid or Insufficient balance

Quick Self-Check Trio

1️⃣ Is the API Key filled in correctly? Check api_key field in model_config.toml 2️⃣ Is the account balance sufficient? Log into the API provider's dashboard to check balance 3️⃣ Is the model name correct? Check if model_identifier is in the provider's supported model list

Solutions

Step 1: Check API Key Configuration

toml

# model_config.toml
[[api_providers]]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
api_key = "sk-your-api-key-here"    # Required! Replace with your actual key
auth_type = "bearer"

Step 2: Verify Key is Valid

bash

# Test DeepSeek API
curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key-here"

Step 3: Check Balance

Log into DeepSeek/OpenAI or other provider's dashboard
Check if account balance is greater than 0
Check if API Key has expired or been disabled

Step 4: Confirm Model Name

toml

# ✅ Correct example
[[models]]
model_identifier = "deepseek-chat"   # Must be a model name supported by the API provider
name = "deepseek-chat"
api_provider = "DeepSeek"

# ❌ Incorrect example
[[models]]
model_identifier = "gpt-4"           # DeepSeek does not support GPT-4!
api_provider = "DeepSeek"

Prevention Tips

🔑 Don't commit Keys to Git — Use environment variables or local configuration files
💰 Set up balance alerts — Enable low-balance email notifications in the API dashboard
📊 Monitor usage — Regularly check token consumption

Scenario 3: Port Occupied

Error Symptoms

Startup reports OSError: [Errno 98] Address already in use
Or [Errno 10048] (Windows)
Error log: 端口 8001 已被占用 (host=127.0.0.1)

Quick Self-Check Trio

1️⃣ Which process is occupying the port? Check in Task Manager / Activity Monitor 2️⃣ Can you close the occupying process? End the occupying process in Task Manager 3️⃣ Can you change MaiBot's port? Edit the configuration file to use another port

Solutions

Method 1: End the Occupying Process Find the process occupying the port in Task Manager (Windows) or Activity Monitor (macOS) and end it. If you don't know which process is occupying it, simply restarting your computer can also free up the port.

Method 2: Change MaiBot's Port

toml

# config/bot_config.toml

# WebUI port (default 8001)
[webui]
port = 8002             # Change to 8002 or another available port

# WebSocket port (default 8000)
[maim_message]
ws_server_port = 8001   # Change to 8001 or another available port

Method 3: Start with a Different Port Simply change the port in the configuration file and restart MaiBot. It's recommended to use less commonly used ports like 8002, 9000, etc.

Prevention Tips

📝 Document port assignments — Avoid multiple services using the same port
🔄 Check after restart — Sometimes old processes aren't cleaned up, may need to manually end them after restart
🔧 Use non-standard ports — e.g., change 8001 to 18001 to reduce conflict probability

Scenario 4: WebUI Page Won't Open

Error Symptoms

Browser shows "This site can't be reached" or "Connection refused" when visiting http://localhost:8001
Page is blank or times out loading
MaiBot is running but WebUI won't open

Quick Self-Check Trio

1️⃣ Did MaiBot really start successfully? Check the terminal for errors 2️⃣ Is the browser address correct? Default is http://localhost:8001 3️⃣ Is the firewall blocking it? Windows Firewall / antivirus software may be blocking

Solutions

Step 1: Confirm MaiBot is Running Check the terminal window where MaiBot is running, look for a log message like this:

WebUI 服务器 启动成功: http://127.0.0.1:8001

If you don't see this, MaiBot hasn't fully started yet. Resolve the startup error first.

Step 2: Check Address and Port

Default address: http://127.0.0.1:8001 (recommend using 127.0.0.1 instead of localhost)
If you changed the port, use your modified port
If deploying on a remote server, replace 127.0.0.1 with the server's IP

Step 3: Check Firewall

Windows: Open "Windows Security" → "Firewall & network protection" → "Allow an app through firewall", ensure Python is allowed
macOS: System Settings → Network → Firewall, check if Python is blocked
Linux: Check iptables or ufw rules

Step 4: Check if Port is Occupied If the port is taken by another program, WebUI won't start. Refer to Scenario 3 for checking port occupancy.

Prevention Tips

🖥️ Check logs after startup — Open the browser only after seeing "WebUI server started successfully"
🔧 Always use 127.0.0.1 — More stable than localhost, avoids DNS resolution issues
🛡️ Temporarily disable firewall — If you're sure it's safe, temporarily disable the firewall for testing

Scenario 5: MCP Configuration Error

Error Symptoms

Startup reports MCP 服务器 {name} 使用 stdio 时必须填写 command
Or MCP 服务器 {name} 使用 streamable_http 时必须填写 url
Or log shows MCP server xxx failed to connect

Quick Self-Check Trio

1️⃣ Is the server address correct? Check mcp.servers[].url or command field 2️⃣ Does the Token/Secret match? Confirm bearer_token matches the MCP server 3️⃣ Is the MCP service running? Confirm the server has started and is accessible

Solutions

Step 1: Check MCP Configuration

toml

# config/bot_config.toml

[mcp]
enable = true

# STDIO type (local process communication)
[[mcp.servers]]
name = "local-filesystem"
enabled = true
transport = "stdio"
command = "node"                          # Required! Startup command
args = ["/path/to/mcp-server/index.js"]   # Command arguments

# HTTP type (remote service)
[[mcp.servers]]
name = "remote-search"
enabled = true
transport = "streamable_http"
url = "https://mcp-search.example.com/sse"    # Required! HTTP endpoint

[mcp.servers.authorization]
mode = "bearer"
bearer_token = "your-bearer-token-here"       # Required! Authentication token

Step 2: Verify MCP Service is Accessible

bash

# Test HTTP type MCP
curl -v https://mcp-search.example.com/sse \
  -H "Authorization: Bearer your-bearer-token-here"

# Test STDIO type MCP
node /path/to/mcp-server/index.js
# You should see the MCP service startup log

Step 3: Check Common Errors

toml

# ❌ Error example 1: stdio mode missing command
[[mcp.servers]]
transport = "stdio"
command = ""              # Error! Must specify startup command

# ❌ Error example 2: HTTP mode missing url
[[mcp.servers]]
transport = "streamable_http"
url = ""                  # Error! Must specify HTTP endpoint

# ❌ Error example 3: Bearer auth missing Token
[mcp.servers.authorization]
mode = "bearer"
bearer_token = ""         # Error! Must specify Token

Prevention Tips

📋 Check each config item — Refer to the MCP server documentation to confirm parameters
🔍 Test before deploying — Use curl to test connectivity before configuring in MaiBot
📝 Document Token changes — Update MaiBot configuration synchronously when Token changes

Scenario 6: Bot Not Replying to Messages

Error Symptoms

Message has been sent to the platform (QQ group / private chat)
Bot has no response at all
No errors in logs, but still no reply

Quick Self-Check Trio

1️⃣ Check the backend terminal output — did it show a message received prompt? 2️⃣ Was a rule matched? Check if keyword/intent rules cover this message 3️⃣ Is the LLM configuration correct? Confirm API Key and model configuration are correct (refer to Scenario 2)

Solutions

Step 1: Check Terminal Output Restart MaiBot and observe the terminal logs, see if there are:

收到消息：... (shows the message reached MaiBot)
正在调用 LLM... (shows it's requesting AI)
发送回复：... (shows the reply was sent) If all of these appear, MaiBot itself is fine — it might be a platform permission or network issue.

Step 2: Check Reply Rules

toml

# Check keyword rules
[[keyword_reaction.keyword_rules]]
keywords = ["你好", "hello"]    # Make sure it includes the message you sent
reaction = "你好呀！"
enabled = true                  # Make sure the rule is enabled

Step 3: Check Rate Limits

toml

# config/bot_config.toml
[chat]
# Check if rate limits are too strict
reply_frequency_limit = 10      # Max 1 reply per 10 seconds

Step 4: Check Platform Permissions

QQ groups: Is the bot muted? Does it have permission to speak?
Private chat: Has the bot been blocked?
Adapter: Is NapCat connected normally?

Step 5: Test LLM Response

bash

# Manually test the API
curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'
# You should receive a reply from the API

Prevention Tips

📊 Monitor logs — Regularly check logs, handle anomalies promptly
🧪 Test new rules — Test whether a rule works after adding it
📝 Document configuration changes — Record changes after modifying reply rules

🟡 High Frequency Errors (Common)

Covers scenarios 7–11, problems encountered relatively often during normal use.

Scenario 7: Plugin Loading Failed

Error Symptoms

Startup reports PluginLoadError, corresponding plugin is grayed out and unavailable in the plugin list
Log shows ImportError, ModuleNotFoundError, or ManifestValidationError
Plugin directory exists but no plugins are loaded

Quick Self-Check Trio

1️⃣ First try reinstalling the plugin with the latest version 2️⃣ Check the log for what dependencies are missing 3️⃣ Confirm Python version is ≥ 3.10 and the plugin is compatible with the MaiBot version

Solutions

Step 1: Try a Different Version Re-download the plugin and choose a version compatible with your MaiBot version. Prioritize official plugins or popular community plugins — they have better compatibility.

Step 2: Install Missing Dependencies Check the log for errors like No module named 'xxx'. If found, the plugin is missing dependencies. Run the following in the plugin directory:

bash

cd plugins/your-plugin-directory
uv sync

Step 3: Read the Full Error Log When starting MaiBot, pay attention to the complete error information in the terminal, look for prompts like:

No module named 'requests'

Install whatever is indicated as missing.

Prevention Tips

Check the documentation before installing a plugin to confirm compatible MaiBot version
Prioritize official plugins or popular community plugins
Regularly update plugins and MaiBot to the latest versions

Scenario 8: Database Error

Error Symptoms

Runtime reports DatabaseError or OperationalError
Startup prompts database migration failed
Log shows database is locked or disk I/O error

Quick Self-Check Trio

1️⃣ Check if multiple MaiBot instances are running simultaneously connecting to the same database 2️⃣ Check if disk space is full (open file manager to check) 3️⃣ Confirm data/maibot.db file permissions are correct (readable and writable)

Solutions

Step 1: Resolve Database Locking

If the log shows database is locked, it means multiple MaiBot instances may be accessing the same database file simultaneously. Close the extra MaiBot processes and keep only one running.

If it's still locked after closing, try deleting the data/maibot.db file and starting fresh (remember to back up first).

Step 2: Repair Corrupted Database

If you suspect database corruption (e.g., after a sudden power outage):

First back up: copy data/maibot.db to a safe location
Restart MaiBot — the program will automatically rebuild or repair the database
If that doesn't work, delete data/maibot.db and let the program recreate it (important prior data needs to be restored from backup)

Step 3: Enable WAL Mode (Reduce Locking Conflicts)

toml

[database]
# Enable WAL mode to reduce multi-process locking conflicts
journal_mode = "wal"

Step 4: Clean Up Disk Space

Open the logs/ folder and delete unneeded old log files. If disk space is critically low, also check other directories for large files.

Prevention Tips

Avoid running multiple MaiBot instances simultaneously connecting to the same database file
Regularly back up data/maibot.db (recommended weekly)
Configure log rotation to prevent log files from filling up the disk
Use WAL mode to reduce locking conflicts

Scenario 9: Network Timeout / Connection Failure

Error Symptoms

LLM request returns APIConnectionError or TimeoutError after being unresponsive for a long time
Log shows Connection refused, Connection reset, or Read timed out
Bot completely unresponsive, but local features work normally

Quick Self-Check Trio

1️⃣ Test network connectivity (curl -v https://api.deepseek.com) 2️⃣ Try a different network (e.g., switch to mobile hotspot) 3️⃣ Confirm the timeout parameter isn't too small (recommended 60–120 seconds)

Solutions

Step 1: Test Network Connectivity

bash

# Test if the API endpoint is reachable
curl -v https://api.deepseek.com

If it connects (returning HTTP 200 or 401 both count as connected), the network is fine. If it times out or can't connect, your network route to the API provider is blocked — try a different network.

Step 2: Increase Timeout

If the network is poor, set a longer timeout:

toml

[[api_providers]]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
api_key = "sk-your-api-key-here"
timeout = 120              # Single request timeout (seconds), can be set to 180 on poor networks
max_retry = 3              # Number of retries on failure
retry_interval = 8         # Retry interval (seconds)

Step 3: Try a Different API Provider

If DeepSeek is unstable, add a backup API in the configuration:

toml

[[api_providers]]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
api_key = "sk-key-1"

[[api_providers]]
name = "Backup"
base_url = "https://api.openai.com/v1"  # Replace with another API
api_key = "sk-your-backup-key"

Prevention Tips

Set reasonable timeout (60–120 seconds) and max_retry (2–3 times)
Try a different network when your network is unstable (e.g., switch to mobile hotspot)
Configure multiple API providers as backups to avoid single points of failure
Regularly check API provider status (follow official announcements)

Scenario 10: Emoji System Error

Error Symptoms

Sending emoji commands has no effect
Emoji generation fails, logs show VLMError or FilterError
Emoji registration fails, prompting quantity limit exceeded

Quick Self-Check Trio

1️⃣ Confirm emoji.vlm_api_key is configured (if using VLM verification) 2️⃣ Check if emoji.filter rules are too strict 3️⃣ Ensure data/emojis/ directory is writable (correct permissions)

Solutions

Step 1: Check VLM Configuration

If using VLM for emoji verification, ensure the API Key is configured:

toml

[emoji]
# VLM API Key (if using visual model for emoji verification)
vlm_api_key = "sk-your-vlm-key"

Step 2: Adjust Emoji Filtering Rules

If emojis are being falsely filtered:

toml

[emoji]
content_filtration = false   # Temporarily disable filtering to check if it's a rule issue

Step 3: Check Directory Permissions

Ensure the data/emojis/ directory is writable. If permissions are wrong, right-click and set read/write permissions in the file manager.

Step 4: Adjust Emoji Quantity Limit

If prompted that the registration quantity has exceeded the limit:

toml

[emoji]
emoji_send_num = 25          # Number of candidates sent at once (1-64)
max_reg_num = 64             # Maximum number of registered emojis
do_replace = true            # Replace old emojis when limit is reached

Prevention Tips

Temporarily disable VLM verification during first use to check if it's a model issue
Enable content_filtration cautiously to avoid false filtering of normal emojis
Regularly clean the data/emojis/ directory, remove unused emojis
Set a reasonable max_reg_num to avoid taking up too much storage space

Scenario 11: Knowledge Graph / Memory System Error

Error Symptoms

Bot replies "I don't remember" or "No relevant information found"
Log prompts knowledge file loading failed
Memory added but cannot be retrieved

Quick Self-Check Trio

1️⃣ Run maibot knowledge rebuild to rebuild the knowledge index 2️⃣ Check if files in data/knowledge/ directory are intact 3️⃣ Confirm knowledge.enabled is true

Solutions

Step 1: Rebuild Knowledge Index

bash

# Use CLI command to rebuild index
maibot knowledge rebuild

# Or click the "Rebuild Index" button in WebUI

Step 2: Check Knowledge Files

bash

# View the knowledge directory
ls -la data/knowledge/

# Confirm file format is correct (JSON or TXT)
# Corrupted files will cause loading failures

Step 3: Enable the Knowledge System

Confirm the knowledge system is enabled in the configuration file:

toml

[knowledge]
enabled = true

Step 4: Limit Single Knowledge Entry Length

If knowledge is too long and exceeds the embedding model's token limit:

toml

[knowledge]
# Maximum length of a single knowledge entry (Token count)
max_chunk_size = 512
# Knowledge chunk overlap size (to avoid context breaks)
chunk_overlap = 50

Step 5: Check Vector Database

If the index is corrupted, delete the contents of data/vector_index/ directory, then rebuild:

bash

maibot knowledge rebuild

Prevention Tips

Control the length of individual entries when adding knowledge to avoid exceeding the embedding model's token limit
Rebuild the knowledge index periodically to keep the index synchronized with knowledge files
Back up data/knowledge/ and data/vector_index/ directories
Use WebUI's knowledge management features to avoid manually editing knowledge files

🟢 Medium Frequency Errors (Specific Scenarios)

Covers scenarios 12–17, problems encountered only in specific operations or configuration scenarios.

Error Symptoms

Opening WebUI page automatically redirects back to login page
After entering password, prompts "Login failed" or "Incorrect password"
API requests return 401 Unauthorized error
Browser console shows Token expired or Invalid session

Quick Self-Check Trio

1️⃣ Clear browser cache — Cookie/LocalStorage may have expired or become corrupted 2️⃣ Check if password is correct — Confirm uppercase/lowercase and special characters are entered correctly 3️⃣ Check WebUI service status — Confirm the service is running and hasn't been restarted

Solutions

Method 1: Clear Cookies and Re-login

bash

# Browser operations:
# 1. Press F12 to open Developer Tools
# 2. Go to Application → Cookies
# 3. Delete all MaiBot-related Cookies
# 4. Refresh the page and re-login

Method 2: Restart WebUI Service

bash

# If password or secret_key has been modified, restart the service
# Docker deployment
docker restart maibot

# Source deployment
# First stop the current process (Ctrl+C), then restart
python bot.py

Method 3: Check secret_key Configuration

toml

# Edit config/bot_config.toml
[webui]
secret_key = "your-secret-key-here"  # Ensure it remains consistent with previous value
session_expire = 7                   # Session validity (days), default 7 days

⚠️ Note: Modifying secret_key will invalidate all logged-in sessions, requiring re-login.

Prevention Tips

Extend session validity — Change session_expire to 30 days
Keep secret_key fixed — Don't change it frequently, otherwise you'll have to re-login each time
Use browser bookmarks — Save the page after logging in to avoid re-entering the password

Scenario 13: Platform Bot Account Not Configured

Error Symptoms

Messages cannot be sent on a platform (e.g., QQ)
Log prompts No bot account configured for platform qq
Adapter is connected but bot is unresponsive
Message sending fails, returns 400 Bad Request

Quick Self-Check Trio

1️⃣ Check platform configuration — Confirm platforms.qq.bot_accounts is filled in 2️⃣ Verify account credentials — Confirm Token/password is correct and hasn't expired 3️⃣ Check adapter logs — Confirm the adapter is connected normally

Solutions

Step 1: Configure Bot Account

toml

# Edit config/bot_config.toml
[platforms.qq]
enabled = true

# Add bot account configuration
[[platforms.qq.bot_accounts]]
uin = "123456789"              # Bot QQ number
token = "your-bot-token"       # Bot Token (fill in according to adapter type)

# If using NapCat adapter, also configure:
[[platforms.qq.bot_accounts]]
uin = "123456789"
adapter = "napcat"
napcat_uin = "987654321"       # NapCat logged-in QQ number

Step 2: Check Adapter Connection

bash

# View adapter logs
# Docker deployment
docker logs maibot | grep -i adapter

# Source deployment
# Observe terminal output, look for "Adapter connected" related logs

Step 3: Verify Account Credentials

QQ platform — Confirm the QQ number can log into NapCat/GoCQQ normally
WeChat platform — Confirm the Token hasn't expired and permissions are correct
Other platforms — Refer to the corresponding adapter's documentation

Prevention Tips

Use a secondary account — Avoid the risk of your main account being banned
Update credentials regularly — Replace Token before it expires
Configure backup accounts — Can quickly switch if the primary account has issues

Scenario 14: Invalid Regular Expression

Error Symptoms

Startup or saving configuration reports re.error: bad escape etc.
Log prompts Invalid regex pattern or 正则表达式编译失败
Keyword rules / message filtering don't work
Configuration page shows "Save failed: regex syntax error"

Quick Self-Check Trio

1️⃣ Check special character escaping — Whether \. \* \+ etc. special characters have backslashes 2️⃣ Check bracket matching — Whether () [] {} are properly paired 3️⃣ Use online tool to test — Verify the regex with regex101.com

Solutions

Method 1: Use Online Regex Testing Tool

text

# Visit https://regex101.com/
# 1. Enter your regex pattern on the left
# 2. Enter test text below
# 3. Check if there are errors and adjust

Method 2: Escape Special Characters

toml

# Error example: not escaped
ban_msgs_regex = ["\d{17}[\dXx"]  # Square brackets not closed

# Correct example: escaped and closed
ban_msgs_regex = [
    "\\d{17}[\\dXx]",            # ID number (double backslash required in TOML)
    "1[3-9]\\d{9}",              # Phone number
    "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",  # Email
]

Method 3: Use Plain Strings Instead of Regex

toml

# If complex matching isn't needed, plain strings are safer
ban_words = ["广告", "加微信", "兼职"]  # Simple keywords, no regex needed

# Avoid writing complex regexes
# ban_msgs_regex = ["(今天 | 明天 | 后天).*(天气 | 气温)"]  # Error-prone
# Use keyword matching instead
ban_words = ["天气", "气温", "温度"]

💡 Tip: Regex in TOML files requires double backslashes \\ for escaping because \ itself is a TOML escape character.

Prevention Tips

Prefer keyword matching — Simple scenarios don't need regex
Test complex regex separately — Validate on regex101.com first before putting it into config
Add explanatory comments — Add comments next to regex to describe what it matches, making maintenance easier

Scenario 15: Keyword Rule Configuration Error

Error Symptoms

Message matches the wrong reply rule
Rule doesn't take effect at all, bot doesn't reply
Priority conflicts, high-priority rules override low-priority ones
Mixed Chinese/English punctuation causing matching failure

Quick Self-Check Trio

1️⃣ Check rule priority — Higher priority rules override lower ones 2️⃣ Confirm rule is enabled — Is enabled = true set? 3️⃣ Test punctuation — Full-width / half-width symbol differences can affect matching

Solutions

Step 1: Check Keyword Rule Configuration

toml

# Edit config/bot_config.toml
[keyword_reaction]

# Pure keyword rules
[[keyword_reaction.keyword_rules]]
keywords = ["你好", "hello", "嗨"]
regex = []
reaction = "你好呀！有什么可以帮你的吗？"
priority = 10                    # Priority, higher number = higher priority
enabled = true                   # Ensure rule is enabled

# Pure regex rules
[[keyword_reaction.regex_rules]]
keywords = []
regex = ["(早安 | 早上好 | 早 [上啊].*)"]
reaction = "早上好！今天又是美好的一天~"
priority = 20
enabled = true

# Keyword + regex mixed rules
[[keyword_reaction.keyword_rules]]
keywords = ["天气"]
regex = ["(今天 | 明天 | 后天).*(天气 | 气温 | 温度)"]
reaction = "让我看看天气预报..."
priority = 15
enabled = true

Step 2: Adjust Priorities

toml

# Priority examples:
# priority = 30 — Highest priority (exact match)
# priority = 20 — Medium priority (regex match)
# priority = 10 — Default priority (normal keywords)
# priority = 1  — Lowest priority (fallback rule)

# Ensure important rules have higher priority than general rules
[[keyword_reaction.keyword_rules]]
keywords = ["帮助", "help"]
reaction = "我可以帮你..."
priority = 30                    # High priority, ensure preferential matching

[[keyword_reaction.keyword_rules]]
keywords = ["吗", "呢", "吧"]     # General question words, lower priority
reaction = "这个嘛..."
priority = 5

Step 3: Test Punctuation Differences

toml

# Full-width punctuation (Chinese input method)
keywords = ["你好，", "你好，"]   # Different commas

# Half-width punctuation (English input method)
keywords = ["hello,", "hello!"]

# Recommended to configure both types of punctuation
keywords = ["你好，", "你好，", "hello", "hello!"]

Prevention Tips

Add comments to rules — Comment the purpose next to each rule
Hierarchical priority management — Exact match > Regex match > Normal keywords > Fallback rule
Test rules regularly — Send test messages in the group to verify matching
Use debug mode — Enable DEBUG logging to see the actual matching chain

Scenario 16: Git Operation Failed (WebUI)

Error Symptoms

Knowledge base sync / Git mirror operation fails in WebUI
Log shows Git clone failed or Permission denied
SSH Key verification fails with Host key verification failed
Git LFS files are too large causing timeout

Quick Self-Check Trio

1️⃣ First check network — Can you access GitHub/Gitee? 2️⃣ Try a public repository — Does a repo that doesn't require login work? 3️⃣ Is the repository too large? — Large files can cause timeout

Solutions

Step 1: Confirm Network Connectivity Check if you can open GitHub or Gitee websites. If not, there's a network issue — resolve that first.

Step 2: Try a Repository That Doesn't Require Login If you get a permission error (Permission denied), try a public repository (one that doesn't need SSH Key) in WebUI. If the public repository syncs normally, it's an SSH permission configuration issue — check your SSH Key settings on GitHub/Gitee.

Step 3: Adjust Git Timeout Configuration If the repository is large, increase the timeout in config/bot_config.toml:

toml

[git_mirror]
timeout = 300                    # Git operation timeout (seconds), default 300 seconds
max_file_size = 100              # Maximum single file size (MB), files larger than this will be skipped

Prevention Tips

Test with a public repository first — Switch to a private repo only after confirming sync works
Avoid large files — Don't put large binary files in the repository

Scenario 17: Log Files Too Large / Disk Space Full

Error Symptoms

System running slowly or crashing
Log rotation fails with No space left on device
Disk usage 100%, cannot write new files
MaiBot startup fails, prompting database locked or write failure

Quick Self-Check Trio

1️⃣ Check disk space — Open file manager to see how much space is left 2️⃣ Check log file size — See how large the logs/ folder is 3️⃣ Check log level — DEBUG level generates a large amount of logs

Solutions

Step 1: Clean Up Log Files Open the logs/ folder and delete unneeded old log files. Generally, only the last few days of logs need to be kept — previous ones can be deleted directly.

Step 2: Configure Log Rotation

toml

# Edit config/bot_config.toml
[logging]
level = "INFO"                 # Use INFO for production, DEBUG for debugging
max_bytes = 10485760           # Maximum 10MB per single file
backup_count = 5               # Keep 5 backup files
enable_rotation = true         # Enable log rotation

Step 3: Clean Up Other Junk Files

Docker users: Clean up unused images and containers to free space
Check ~/.cache/ directory, delete any unneeded cache files

Step 4: If Still Not Working, Use a Different Drive If the current disk is indeed too small, consider moving MaiBot's logs and data directories to a larger disk.

Prevention Tips

Use INFO level in production — Avoid excessive DEBUG logs
Configure log rotation — Limit log file size and count
Regular cleanup — Set up crontab to automatically clean old logs weekly
Mount to separate disk — Mount the log directory to a separate disk partition
Monitor disk space — Set up alerts, notify when usage exceeds 80%

⚪ Low Frequency Errors (Rare)

Covers scenarios 18–19, problems rarely encountered but may appear in special operations.

Scenario 18: Person/User System Data Anomaly

Error Symptoms

User profile loading fails in WebUI, shows blank or error
Character card information lost, previously set personality/background is gone
When binding accounts, prompts "User already exists" or "Foreign key constraint failed"

Quick Self-Check Trio

1️⃣ Did you directly modify the SQLite database file? 2️⃣ Is the JSON format of character cards in data/persons/ folder correct? 3️⃣ Are there multiple MaiBot instances accessing the same database simultaneously?

Solutions

Rebuild User Index

bash

maibot person rebuild

Check Character Card Format

bash

# Enter the character card directory
cd data/persons/

# Validate JSON format (using a character as an example)
python -m json.tool "character-name.json" > /dev/null

Repair Database (Proceed with Caution)

bash

# Backup database
cp data/maibot.db data/maibot.db.bak

# Use WebUI to manage users, do not operate on the database directly

Prevention Tips

🖥️ Use WebUI for management — Don't modify the database file directly
💾 Back up regularly — data/persons/ and data/maibot.db are important
🔒 Avoid concurrent access — Don't start multiple MaiBot instances connecting to the same database

Scenario 19: Adapter WebSocket Disconnect Reconnect Loop

Error Symptoms

Adapter logs continuously:

[WebSocket] Connection closed, reconnecting...
[WebSocket] Reconnecting in 3s...
[WebSocket] Connection established
[WebSocket] Connection closed, reconnecting...

Message sending and receiving is unstable, sometimes works and sometimes doesn't.

Quick Self-Check Trio

1️⃣ Is the adapter.ws_url address and port correct? 2️⃣ Is the network stable? (Between server and adapter) 3️⃣ Is the server-side WebSocket service running normally?

Solutions

Check WebSocket Address

toml

# Open the adapter configuration file
[adapter]
ws_url = "ws://127.0.0.1:8000"  # Ensure the address and port are correct

Adjust Reconnect Interval

toml

[adapter]
reconnect_interval = 5  # Increase the interval to avoid frequent reconnection (unit: seconds)

Check Server Status Check MaiBot's terminal output to confirm the WebSocket service is running normally (you should see logs like WebSocket 服务启动成功).

Enable Heartbeat Keepalive (Advanced) If the network environment is poor, enable heartbeat in the adapter configuration:

toml

[adapter]
enable_heartbeat = true
heartbeat_interval = 30  # Send a heartbeat every 30 seconds

Prevention Tips

🌐 Ensure network stability — The network between server and adapter should be reliable
🔔 Enable heartbeat detection — Recommended for long connections to keep alive
📊 Monitor logs — Investigate promptly if frequent reconnection is detected
🔄 Consider using process management — systemd/supervisor can automatically restart services

⚡ 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 → Scenario 13: Platform Bot Account Not Configured — Request parameter error, message sending failed

HTTP 401 Unauthorized 🟥 Fatal → Scenario 2: API Key Error / Insufficient Balance — API Key invalid or missing

HTTP 401 Unauthorized 🟧 Severe → Scenario 12: WebUI Login Failed / Token Expired — Session expired or Token invalid

HTTP 402 Payment Required 🟧 Severe → Scenario 2: API Key Error / Insufficient Balance — Account balance insufficient

HTTP 403 Forbidden 🟥 Fatal → Scenario 2: API Key Error / Insufficient Balance — API Key insufficient permissions

HTTP 429 Too Many Requests 🟧 Severe → Scenario 9: Network Timeout / Connection Failure — Request frequency too high, rate limited

HTTP 500 Internal Server Error 🟧 Severe → Scenario 9: Network Timeout / Connection Failure — API server internal error

HTTP 502 Bad Gateway 🟧 Severe → Scenario 9: Network Timeout / Connection Failure — Gateway error, upstream service unreachable

HTTP 503 Service Unavailable 🟧 Severe → Scenario 9: Network Timeout / Connection Failure — Service temporarily unavailable (overload/maintenance)

Common Error Keyword Index

Address already in use / [Errno 98] / [Errno 10048] 🟧 Severe → Scenario 3: Port Occupied — Port is already in use by another process

APIConnectionError 🟧 Severe → Scenario 9: Network Timeout / Connection Failure — API connection failed

Connection refused / 无法访问此网站 🟥 Fatal → Scenario 4: WebUI Page Won't Open — WebUI service not started or port unreachable

database is locked 🟧 Severe → Scenario 8: Database Error — Database locked by multiple processes

DatabaseError / OperationalError 🟧 Severe → Scenario 8: Database Error — Database operation exception

FileNotFoundError 🟥 Fatal → Scenario 1: Configuration File Not Found or Incorrect Format — Configuration file does not exist

FilterError 🟨 Warning → Scenario 10: Emoji System Error — Emoji filter rule false positive

ImportError / ModuleNotFoundError 🟧 Severe → Scenario 7: Plugin Loading Failed — Plugin dependency missing

No space left on device 🟧 Severe → Scenario 17: Log Files Too Large / Disk Space Full — Disk space insufficient

PluginLoadError 🟧 Severe → Scenario 7: Plugin Loading Failed — Plugin loading exception

re.error / bad escape 🟨 Warning → Scenario 14: Invalid Regular Expression — Regex syntax error

TimeoutError 🟧 Severe → Scenario 9: Network Timeout / Connection Failure — Request timeout

Token expired 🟨 Warning → Scenario 12: WebUI Login Failed / Token Expired — Login session expired

TOML syntax error 🟥 Fatal → Scenario 1: Configuration File Not Found or Incorrect Format — Configuration file format error

ValueError 🟥 Fatal → Scenario 5: MCP Configuration Error — MCP server configuration parameter invalid

VLMError 🟨 Warning → Scenario 10: Emoji System Error — Vision language model call failed

知识加载失败 🟧 Severe → Scenario 11: Knowledge Graph / Memory System Error — Knowledge file corrupted or format error

Session 过期 🟨 Warning → Scenario 12: WebUI Login Failed / Token Expired — Browser session expired

🆘 Getting Help Guide

🤔 Self-Check Before Asking

Before asking for help, take 2 minutes to do the following checks — most problems can be resolved on your own:

📖 1. Consult the Official Documentation : Your problem has likely already been answered in various scenarios of this document. Search through it first — it saves time and effort.

🔍 2. Check the Error Logs : The logs will specify the specific error cause and stack trace — this is the primary clue for locating the problem. Don't know how to export them? See "How to Get Logs" below.

⚙️ 3. Review Recent Changes : Think back to what configuration you recently changed, what plugins you installed, or what versions you updated. Try reverting to the last working state to confirm if something was changed incorrectly.

🌐 4. Search Known Issues : Use error keywords to search GitHub Issues or search engines to see if others have encountered the same problem.

📋 Information Checklist for Submitting an Issue

When submitting an Issue on GitHub, please be sure to include the following information. Issues missing key information may be delayed:

🖥️ System and Environment : Operating system type and version, deployment method (source/Docker), Python version (for source deployment)

🔢 MaiBot Version : Run git log --oneline -1 to view the current commit, or get the version number from the bottom of WebUI

📄 Complete Error Logs : Log snippets containing the stack trace (traceback) — don't just screenshot a small portion. See "How to Get Logs" below

⚙️ Related Configuration : Configuration content related to the problem (be sure to redact sensitive information like API Keys)

🎯 Reproduction Steps : Specific steps from startup to error occurrence — the more detailed, the better

🌐 Community Support Channels

💬 QQ Group : Join the MaiBot user community to exchange experiences with other users. Group number: [Please fill in group number]

🐱 GitHub Issues : If you've confirmed it's a bug or feature suggestion, please submit at GitHub Issues. Remember to search first to avoid duplicates

📖 Official Documentation Site : For the latest and most comprehensive documentation, visit MaiBot Documentation Site

💬 GitHub Discussions : For feature discussions and technical questions, visit GitHub Discussions to join the community conversation

📝 How to Get Logs

Depending on your deployment method, the way to get logs differs:

🐍 Source Deployment : The terminal output where MaiBot is running is the most direct log. If the terminal has been closed, check the log files as follows:

bash

cat logs/maibot-*.log

If you need more detailed logs, enable DEBUG level in config/bot_config.toml:

toml

[log]
log_level = "DEBUG"

🐳 Docker Deployment : Use the docker logs command to view container logs:

bash

# View all logs
docker logs maibot

# Continuously follow log output
docker logs -f maibot

# View only the last 100 lines
docker logs --tail 100 maibot

🪟 Windows Deployment : Log files are located in the logs\ directory by default:

powershell

type logs\maibot-*.log

# Or using PowerShell
Get-Content logs\maibot-*.log

💡 Tip: After getting the logs, wrap them in a ``` code block and paste them into the Issue. If the logs are very long, only include the section from the last startup to the error — don't paste thousands of lines of complete logs.

📋 Error Troubleshooting Flowchart

Not sure which category your problem falls into? Follow the flowchart to find the corresponding section.

🔧 Error Troubleshooting FAQ ​

🔴 Extremely High Frequency Errors (Inevitable for New Users) ​

Scenario 1: Configuration File Not Found or Incorrect Format ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 2: API Key Error / Insufficient Balance ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 3: Port Occupied ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 4: WebUI Page Won't Open ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 5: MCP Configuration Error ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 6: Bot Not Replying to Messages ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

🟡 High Frequency Errors (Common) ​

Scenario 7: Plugin Loading Failed ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 8: Database Error ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 9: Network Timeout / Connection Failure ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 10: Emoji System Error ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 11: Knowledge Graph / Memory System Error ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

🟢 Medium Frequency Errors (Specific Scenarios) ​

Scenario 12: WebUI Login Failed / Token Expired ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 13: Platform Bot Account Not Configured ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 14: Invalid Regular Expression ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 15: Keyword Rule Configuration Error ​

Error Symptoms ​

Quick Self-Check Trio ​

Solutions ​

Prevention Tips ​

Scenario 16: Git Operation Failed (WebUI) ​

🔧 Error Troubleshooting FAQ

🔴 Extremely High Frequency Errors (Inevitable for New Users)

Scenario 1: Configuration File Not Found or Incorrect Format

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 2: API Key Error / Insufficient Balance

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 3: Port Occupied

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 4: WebUI Page Won't Open

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 5: MCP Configuration Error

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 6: Bot Not Replying to Messages

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

🟡 High Frequency Errors (Common)

Scenario 7: Plugin Loading Failed

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 8: Database Error

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 9: Network Timeout / Connection Failure

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 10: Emoji System Error

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 11: Knowledge Graph / Memory System Error

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

🟢 Medium Frequency Errors (Specific Scenarios)

Scenario 12: WebUI Login Failed / Token Expired

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 13: Platform Bot Account Not Configured

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 14: Invalid Regular Expression

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 15: Keyword Rule Configuration Error

Error Symptoms

Quick Self-Check Trio

Solutions

Prevention Tips

Scenario 16: Git Operation Failed (WebUI)