From 7566b36244124ae016277a9877ac43a7f99364c0 Mon Sep 17 00:00:00 2001
From: "astrbot-docs-agent[bot]"
 <astrbot-docs-agent[bot]@users.noreply.github.com>
Date: Mon, 23 Feb 2026 14:48:44 +0000
Subject: [PATCH] docs: update for AstrBotDevs/AstrBot#5376

---
 en/faq.md | 13 +++++++++++++
 zh/faq.md | 13 +++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/en/faq.md b/en/faq.md
index 3955f54..9636a65 100644
--- a/en/faq.md
+++ b/en/faq.md
@@ -54,6 +54,19 @@ This is because the provider's API returned empty text. Try the following steps:
 5. Lower the maximum conversation count setting
 6. Switch to another model from the same provider / a different provider
 
+### Startup Error: `JSONDecodeError: Unexpected UTF-8 BOM`
+
+On Windows, some text editors (like Notepad) automatically add a UTF-8 BOM (Byte Order Mark) when saving JSON files, causing AstrBot to fail to start.
+
+**Solutions:**
+
+1. Use an editor that supports UTF-8 without BOM (such as VS Code, Notepad++) to open the configuration file
+2. When saving, select "UTF-8" encoding (without BOM)
+3. Or modify configurations directly in the AstrBot WebUI to avoid manually editing JSON files
+
+> [!NOTE]
+> AstrBot has added compatibility handling for UTF-8 BOM in newer versions. It is recommended to update to the latest version to avoid this issue.
+
 ## Plugin Related
 
 ### Cannot Install Plugin
diff --git a/zh/faq.md b/zh/faq.md
index a520eb4..7a4af54 100644
--- a/zh/faq.md
+++ b/zh/faq.md
@@ -71,6 +71,19 @@
 5. 降低最大对话次数设置
 6. 切换使用同一供应商的其他模型，或不同供应商的模型
 
+### 启动时报错 `JSONDecodeError: Unexpected UTF-8 BOM`
+
+在 Windows 系统上，某些文本编辑器（如记事本）保存 JSON 文件时会自动添加 UTF-8 BOM（字节顺序标记），导致 AstrBot 无法正常启动。
+
+**解决方法：**
+
+1. 使用支持无 BOM 编码的编辑器（如 VS Code、Notepad++）打开配置文件
+2. 另存为时选择 "UTF-8" 编码（不带 BOM）
+3. 或者直接在 AstrBot WebUI 中修改配置，避免手动编辑 JSON 文件
+
+> [!NOTE]
+> AstrBot 已在新版本中增加了对 UTF-8 BOM 的兼容处理，建议更新到最新版本以避免此问题。
+
 ## 插件相关
 
 ### 插件安装不上