ASSET_SOURCE_REQUIRED | materials 需要 --client-jar、--assets 或自包含资源包 |
INPUT_TOO_LARGE | 文件超过输入上限；确认文件完整，或在可信环境中使用 --force-limits |
MESH_LIMIT_EXCEEDED / PAGE_LIMIT_EXCEEDED | 拆分结构，或在可信环境中使用 --force-limits |
| 画面全是纯色块 | 没有提供资源包，或对应模型/贴图缺失；运行 materials --json 检查 |
| 大量 missing textures | 客户端 jar 版本与模型不匹配，或 overlay 资源包不完整 |
INVALID_RENDER_OPTIONS: threads | --threads 或请求中的线程数超过 256 |
INVALID_NBT / INVALID_LITEMATIC | 文件损坏、版本不支持或结构不符合预期；先运行 validate |
serve 没有输出 hello | 查看 worker stderr；检查资源包路径和启动参数 |
| 输出目录无法写入 | 确认容器/服务用户对 outputDir 有写权限 |
| 渲染很慢或内存不足 | 使用 capacity、降低分辨率/超采样、减少并发，并保持 --stream-mesh 开启 |
