WLED 错误代码:错误 7、8、9、12、19 和 91 的含义与修复方法
WLED 定义的每一个错误代码(1 到 101):网页界面提示的含义、固件中触发它的原因,以及修复方法。另附“issue loading your presets”的处理办法。
本文作者 Jamie Conde 在 MeowScript 开发 WLED Max。 WLED Max 是一款独立 App,与官方 WLED 项目无关,也未获其认可。
WLED 会在网页底部用一条红色的短横幅显示错误,例如 Error 8: Effect RAM depleted!。数字来自固件中的一个列表(wled00/const.h),旁边那句文字就是您能得到的全部解释。本页逐一讲解该列表定义的每个代码、真正触发它的原因,以及该怎么处理。
大家搜索最多的代码排在前面。完整表格在页面下方。
横幅只显示一次。WLED 会把错误交给第一个向灯请求状态的页面或 App,然后清除它。如果 Home Assistant 或某个手机 App 正在轮询这盏灯,它们可能先把错误取走,您的浏览器就永远看不到。想看到代码,请在问题发生后立刻刷新页面。
错误 7:No RAM for buffer(缓冲区内存不足)
仅 WLED 16。 灯尝试为某个分段的像素预留内存,但内存不够。WLED 随后会关闭该分段,所以很多人会把这个问题描述成“我的分段消失了”。
原因:
- 对这块芯片来说 LED 太多,通常是 ESP8266,或者是大型 2D 矩阵。
- 分段很多,每个分段都有自己的缓冲区。
- 在支持播放图片的版本上,2D 矩阵上显示图片或 GIF。图片同样占内存。
修复方法:减少 LED 数量,合并用不上的分段,或者把大型装置换到 ESP32 上。带 PSRAM 的开发板(很多 ESP32-S3 开发板,以及 ESP32 WROVER 模块)空间大得多,因为 WLED 16 会尽可能把像素缓冲区放进 PSRAM。
错误 8:Effect RAM depleted(效果内存耗尽)
WLED 0.15 和 16。 某个效果申请工作内存(像 Fire 2012 或粒子效果使用的暂存空间)却没有拿到。WLED 对所有分段的效果内存总量设了上限(0.15 在所有开发板上都限制,16 只在没有 PSRAM 的开发板上限制),所以几个分段各跑一个重量级效果,就算灯看起来很闲,也可能碰到上限。
WLED 16 在另外两种情况下也用同一个代码,两种都值得了解:
- 内存持续偏低 15 秒。 WLED 会把所有分段切换为 Solid 以释放内存,并显示错误 8。如果内存持续偏低 30 秒,它会删除除一个以外的所有分段;到 45 秒时,它会从头重建 LED 灯带并重新连接 Wi-Fi。
- 某个 LED 输出需要的内存超过 WLED 允许的上限。 该输出会以占位符形式添加,所以接在上面的 LED 保持熄灭。保存 LED 设置后您会看到错误 8。
修复方法:使用更轻量的效果(Solid、Solid Pattern 和 Breathe 完全不需要效果内存),减少同时运行重量级效果的分段数量,或者减少每个输出上的 LED 数。如果您的分段总是自己变成 Solid,原因几乎都在这里。
错误 9:JSON parsing error(JSON 解析错误)
所有版本(横幅文字从 0.15 起出现)。有东西向灯发送了它无法读取的 JSON,请求被以 HTTP 400 拒绝。灯上什么都没有改变。
常见原因:
- 弯引号。 您从备忘录 App 或聊天窗口复制了命令,
"变成了“和”。iPhone 的智能标点默认就会这样做。先粘贴到纯文本编辑器里,或者重新输入引号。 - 末尾多了逗号、使用了单引号,或者带有注释。JSON 不允许这些。
- 请求太大。JSON 缓冲区在 ESP8266 上约 10 KB,在 ESP32 上为 24 到 32 KB,一个带很多分段或很长单颗 LED 颜色列表的预设可能超出而解析失败。
- 通过 WebSocket 连接时,一条消息被拆成多个数据包到达。WLED 不会把它们重新拼起来,而是回复错误 9。
如果您在网页界面手工输入预设,预设编辑器会在大多数此类问题到达灯之前拦住它们:您看到的是“Syntax error in custom JSON API command”,而不是错误 9。
错误 12:Preset not found(找不到预设)
所有版本。 有东西要求灯加载一个不存在的预设槽位。删除或重新编号预设之后这很常见,因为 WLED 里没有任何机制会去更新指向这些预设的地方:
- Config›LED & Hardware(0.14 和 0.15 上是 LED Preferences)中的 Apply preset at boot。
- Config > Time & Macros 中的定时器、按键动作和 Alexa 预设。
- 播放列表里的条目。
- 发送
{"ps":N}的 Home Assistant 自动化、脚本或遥控器。
逐项检查这些地方里是否有错误提示的那个槽位号。如果槽位确实存在却仍然出现错误 12,预设文件本身可能已损坏,见下文的“issue loading your presets”。
关于开机预设和槽位的更多内容,见 WLED 预设与开机预设。
错误 19:A filesystem error has occurred(文件系统错误)
所有版本。 这是一个泛指的文件系统故障。在当前源码中它只来自一处:WLED 尝试创建一个空的 presets.json(在启动时,或在您保存预设而该文件已丢失时),但文件写不进去。在编译时带 EEPROM 支持的 0.14 和 0.15 版本上,当来自很早期 WLED(EEPROM 时代)的旧预设转换失败时,也会出现这个错误。
所以错误 19 的意思是闪存无法写入。通常是闪存满了,有时是写入过程中断电导致文件系统损坏。
按顺序尝试:
- 能备份的先备份:Config > Security & Updates > Backup configuration,如果可以的话再 Backup presets。
- 删除预设或您上传过的文件(ledmap、图片、自定义调色板)来释放空间。
- 如果反复出现,就做一次恢复出厂设置(同一页面,勾选 Factory reset 并保存,这会清除所有设置和预设),或者通过 install.wled.me 重新刷写固件,然后恢复您的备份。
错误 91:Brownout Restart(欠压重启)
仅 WLED 16,仅 ESP32 开发板。 芯片因为供电电压跌得太低而重启。WLED 在启动时读取重启原因,并在下一次加载页面时显示 91。在 ESP8266 上欠压和普通断电没有区别,所以您在那里永远不会看到 91,而 0.14 和 0.15 根本不报告它。
对于 LED 灯带,原因几乎总是供电:
- 电源对您使用的亮度下的 LED 来说太小。全白是最坏情况。
- 电源到控制器之间的线太细或太长,LED 变亮时电压就下垂。
- 控制器由笔记本电脑的 USB 口或一个弱手机充电器供电。
- 没有设置亮度上限。
修复方法:在 LED 设置页设置 Maximum PSU Current(0.14 上叫 Maximum Current),让 WLED 把亮度限制在电源能供应的范围内;在长灯带两端补电;并选用留有余量的电源(比计算值高约 20%)。具体数字和截图见 用手机设置 WLED。如果您的灯还时不时掉线,也请读一读 WLED 为什么会离线。
错误 90:Unexpected Restart(意外重启)
WLED 16。 灯崩溃了,或者被看门狗重置,重启后它会告诉您。偶尔出现一次 90 不值得追查。
如果它一再崩溃,WLED 16(以及 0.15.5)会自行介入。连续崩溃 5 次、每次间隔不到两分钟,它就当作启动循环处理,每循环一次尝试一步:先恢复最后一份正常的配置备份,然后重置配置,再然后(仅 ESP32)启动上次更新之前安装的固件。所以如果一连串重启之后您的设置看起来变了,原因就在这里。
常见诱因是对开发板来说太重的效果或用户模块、错误的 LED 设置(引脚、类型或数量),以及还不到欠压程度的供电问题。如果它是在固件更新之后才开始的,见 通过 OTA 更新 WLED。
“Sorry, there was an issue loading your presets!”
这一条没有编号。当网页界面读不出 presets.json 时,会在 Presets 标签页显示它,原因要么是灯没有应答,要么是文件已经不再是合法的 JSON(保存时断电就会造成这种情况)。
- 在浏览器中打开
http://<your-light-ip>/presets.json。如果能看到您的预设,说明文件没问题,只是连接短暂出了问题。刷新页面即可。 - 如果您常用的浏览器以前看过您的预设,这条提示还会显示“Here is a backup of the last known good state”,并带一个 Copy to clipboard 按钮(从 0.15 起还有 Restore 按钮)。这份备份存在浏览器里,不在灯上。先把它复制到安全的地方,再恢复。
- 否则,在 Config > Security & Updates > Restore presets 下恢复一份已保存的
presets.json。这会替换文件中的全部内容。
养成 备份配置和预设 的习惯,这件事就从一个糟糕的夜晚变成两分钟就能修好的小事。
WLED 的全部错误代码
| 代码 | 网页界面文字 | 含义 | 版本 |
|---|---|---|---|
| 1 | Denied! | 启用了设置 PIN 但没有输入,所以设置更改被拒绝 | 全部(文字从 0.15 起) |
| 2 | (无) | 0.14:旧的 EEPROM 代码,未使用。0.15 和 16:“concurrency”,已定义但从未触发 | 实际不会出现 |
| 3 | Buffer locked! | 灯正忙于处理另一个 JSON 请求 | 全部 |
| 4 | (空白) | 未实现:灯不认识的 /json/... 地址,或者在 16 上把仅限 2D 的效果用在 1D 灯带上、把 1D 粒子效果用在只有一颗 LED 的分段上,或者滚动文字的字体文件损坏 | 0.15、16 |
| 7 | No RAM for buffer! | 分段像素的内存不足 | 16 |
| 8 | Effect RAM depleted! | 效果内存不足,或者(16)内存偏低或某个 LED 输出太大 | 0.15、16 |
| 9 | JSON parsing error! | 灯收到了无法读取的 JSON | 全部 |
| 10 | Could not mount filesystem! | 闪存文件系统没有启动 | 全部 |
| 11 | Not enough space to save preset! | 文件系统已满 | 全部 |
| 12 | Preset not found. | 请求了一个不存在的预设槽位 | 全部 |
| 13 | Missing ir.json. | 设为 JSON 模式的红外遥控器发送了一个码,但灯上没有 ir.json | 全部 |
| 14 | (无) | 缺少 remote.json;该检查已被注释掉,所以永远不会触发 | 实际不会出现 |
| 19 | A filesystem error has occured. | 泛指的文件系统故障,通常发生在创建 presets.json 时 | 全部 |
| 30、31、32 | (无) | 过温、过流、欠压。源码中标记为“not implemented” | 实际不会出现 |
| 33 到 37 | (无) | 16 中定义的低内存代码,尚未触发(它们的网页界面文字被注释掉了) | 实际不会出现 |
| 90 | Unexpected Restart. | 灯在崩溃或看门狗重置后重启 | 16 |
| 91 | Brownout Restart. | 灯因供电电压下跌而重启 | 16,ESP32 |
| 100 | Note 100: Please reboot WLED to activate changed settings. | 某项硬件设置需要重启(在 16.0.1 上:ESP32-S3 上的 HUB75 面板更改) | 16 |
| 101 | Note 101: Please switch your device off and back on. | 某项硬件设置需要断电重启;已定义,16.0.1 中尚未使用 | 16 |
0.14 的网页界面只有 10、11、12、13 和 19 的文字,所以其他代码都显示为“Error N:”,后面什么都没有。较新版本上的错误 4 也是如此。“occured”这个拼写错误来自固件本身。
其余代码简述
错误 1(Denied)。 您在 Config > Security & Updates 下设置了 PIN,而有东西试图在不输入 PIN 的情况下更改设置。在网页界面里输入 PIN,或者在正在写入的 App 或脚本里输入。
错误 3(Buffer locked)。 WLED 一次只处理一个 JSON 请求。在 0.15 上,期间到达的第二个请求会得到带错误 3 的 HTTP 503(在 0.14 上只有读取请求会这样,写入请求则得不到任何应答)。WLED 16 改为让 HTTP 请求排队等待,但 WebSocket 客户端仍可能收到错误 3。如果您经常看到它,说明有东西在高频轮询:Home Assistant 集成、几个打开的浏览器标签页加上一个 App 同时在跑。关掉不需要的。
错误 10(Could not mount filesystem)。 通常是刷固件时用了不适合该开发板的闪存布局,或者闪存芯片正在失效。用网页安装器重新刷写,并让它先擦除开发板。设置和预设会丢失,所以请从备份恢复。实际上挂载失败通常表现为错误 19,因为 WLED 会立刻尝试创建 presets.json,而那一步也会失败。
错误 11(Not enough space)。 只有在剩余空间足以容纳整个文件的一份完整副本再加约 9 KB 时,WLED 才会保存预设。一块存了很多带分段布局的预设的 ESP8266 会最先用光空间。删除不用的预设,或者移除不再需要的上传文件。
错误 13(Missing ir.json)。 在 Config > LED & Hardware(0.14 和 0.15 上是 LED Preferences)中红外接收器被设为“JSON remote”类型,却没有上传 ir.json。上传一个,或者在列表中选择您遥控器的型号。
来自 App 的提示
App 不显示 WLED 的编号,它们有自己的措辞。WLED Max(iOS 和 Android)中有两条提示直接对应固件状态:
- “设备正忙,没有接受更改。”(Android 上是“设备正忙,没有接受这项更改。”)灯一直回复错误 3,App 重试几次后放弃了。等几秒再试,并查找是否有别的东西在轮询这盏灯。
- “设备发来了意外的响应。它运行的固件版本可能不兼容。” 灯有应答,但返回的是 HTTP 错误或 App 无法使用的内容。可能是非常老的 WLED、完全不同的固件,或者灯在请求中途重启了。
App 在修改 presets.json 之前也会先检查它。如果文件已损坏,App 不会覆盖它,而是提议保存一份原始文件的副本(iOS:保存文件副本;Android:警告中的 备份原始文件,或“预设”标签页中的 保存文件副本)。
如果灯完全没有应答,那是网络问题而不是 WLED 错误,WLED App 找不到您的灯 会逐一讲解原因。
常见问题
WLED 错误代码列表在哪里? 在 WLED 源码的 wled00/const.h 中,紧挨着 ERR_ 名称。网页界面对每个代码的提示文字在 wled00/data/index.js 中。
出现错误是不是说明我的开发板坏了? 很少。大多数代码关于内存(7、8)、预设(12)或供电(91)。重新刷写后仍反复出现的错误 10 和 19 才是指向硬件的。
为什么刷新页面后错误就消失了? WLED 报告一次之后就清除错误。只有问题再次发生它才会再出现。