启动报错

本页汇总直接运行加载器 Jar（见加载器命令行）时最常见的报错与解决办法。所有错误都会打印在启动控制台中，排查时请先完整查看日志输出。

用启动器时不会看到这些报错：启动器负责挑 Java、准备运行环境，出问题的表现与处理方式见使用桌面版与使用移动版。

Java 版本问题

UnsupportedClassVersionError

java.lang.UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime

原因：当前 Java 版本低于 17。加载器与 Mixin 的类文件都按 Java 17 编译，更低的 JVM 认不出来。

解决：换用 17 到 27 之间的 JDK，并确保命令行中的 java 指向它：

java -version   # 确认主版本号在 17–27 之间

17 是 Copper 的 Mixin 引擎的下限。游戏本身的要求会更高：Mindustry v9 起要求 Java 25。换成 v9 的游戏 Jar 之后，这里要挑的就是 25–27 之间的 JDK，用更低的版本启动同样会抛出这个错误。

Unsupported class file major version

Error loading class: java/lang/Object (java.lang.IllegalArgumentException: Unsupported class file major version 72)

原因：当前 Java 版本高于加载器支持的上限（17–27）。Mixin 解析标准库类时读的是运行中 JRE 的 modules，字节码版本随本机 JDK 走；加载器内置的 ASM 只认到类文件主版本 71（Java 27），在更新的 JDK 上就会在这个版本号上卡住。

解决：换回 27 及以下的 JDK。上限、ASM 与支持范围的关系见与 Minecraft Mixin 的差异 · Java 版本支持扩展。

Unable to load library / 找不到 Java

原因：Java 未安装或未加入 PATH。

解决：重新安装 Java，或使用完整路径调用，例如：

/usr/lib/jvm/java-17-openjdk-amd64/bin/java -jar CopperLoader.jar -G mindustry.jar

加载器无法启动

no game jar provided

原因：没有通过 -G 参数指定游戏 Jar。

解决：

java -jar CopperLoader.jar -G mindustry.jar

failed to read game

原因：游戏 Jar 不是有效的 Mindustry Jar（缺少 version.properties），或文件损坏。

解决：重新下载官方 Mindustry 桌面版 Jar。

failed to read loader version

原因：加载器 Jar 不完整或不是正式的 Copper 发布包。

解决：从 Release 重新下载。

core mod is not found

原因：<数据目录>/copper/mods/copper-core.jar 缺失（被删除或从未成功释放）。

解决：删除整个 <数据目录>/copper/mods/ 下的残留文件后重新启动，让加载器重新释放核心模组。

模组加载失败

failed to read mod

完整错误：failed to read mod: <文件>

原因：模组 Jar 缺少元数据文件（copper.mod.json 或 copper.mod.hjson），或元数据格式错误、版本号不受支持。

解决：确认这是针对 Copper 的模组；联系模组作者更新。

failed to load mod meta

完整错误：failed to load mod meta: <文件>

原因：元数据文件内容解析失败（例如 JSON 语法错误、必填字段缺失）。

解决：检查文件是否为有效的 JSON/HJSON，必填字段是否齐全（见模组元数据）。如非玩家能解决的问题，联系模组作者。

found duplicated mod

完整错误：found duplicated mod: <id>

原因：两个模组文件声明了相同的模组 id。

解决：删除重复的模组文件，只保留一个。

模组没有出现在日志里（非 Java 模组）

原因：Copper 只收录带 Java 主类的模组。Copper 模组的元数据本来就要求 main，因此这种情况只会出现在原版 Mindustry 模组上：mod.json 未声明 main，或 main 指向的 .class 在 Jar 内不存在（这条约束见类隔离机制）。

解决：纯脚本模组的脚本仍由游戏自身加载，不会因为没被 Copper 收录而失效；如果该模组本应以 Java 模组形式加载，请检查它的 main 字段与 Jar 内容是否一致，并联系模组作者。

依赖与冲突错误

这些错误说明当前安装的模组集合不满足某模组的依赖/冲突声明。错误信息中的 A : B 表示「模组 A 与模组 B（或版本）之间的关系」。

failed to find dependency

完整错误：failed to find dependency for A : B

原因：模组 A 声明依赖模组 B，但 B 未安装。

解决：安装 B。注意 B 可能存放在 copper/mods/ 或 mods/ 任意一个文件夹中。

dependency is not supported

完整错误：dependency is not supported by A : B x.y.z

原因：依赖模组 B 已安装，但版本 x.y.z 不满足 A 的要求。

解决：将 B 升级/降级到 A 要求的版本范围。

mod is conflict with

完整错误：mod is conflict with A : B x.y.z

原因：已安装的模组 B 与模组 A 声明了显式冲突。

解决：移除 B 或 A 中的其中一个。

game version is rejected

完整错误：game version is rejected by A : 版本号

原因：模组 A 要求的游戏版本范围与当前游戏 Jar 不匹配。报错里的 A 是 copper:core 时，说明游戏版本低于加载器支持的下限——官方发行版 146.0 及以上、BE 构建号 24369 及以上（见版本、依赖与冲突 · 加载器支持的游戏版本）。

解决：更换游戏 Jar（正式版/BE 版本变化会影响此判断），或联系模组作者确认支持的版本。游戏版本号的构成见版本、依赖与冲突 · 游戏版本号是如何生成的。

loader version is rejected

完整错误：loader version is rejected by A : 版本号

原因：模组 A 要求的加载器版本与当前加载器不匹配。

解决：升级加载器到最新版本。

one or more rings were found in mod dependency path

原因：模组之间存在循环依赖。

解决：移除相关模组之一，并联系模组作者修复。

Mixin 相关错误

failed to find mixin config

完整错误：failed to find mixin config in copper assets of mod A : <路径>

原因：模组 A 声明了 Mixin 配置，但 Jar 内缺少对应的配置文件（应位于 assets/copper/<路径>）。

解决：重新安装完整版本的模组 Jar；仍失败则联系模组作者。

Mixin 注入失败

表现：启动崩溃，日志中出现以 mixin: 为前缀的报错。

原因：Mixin 注入目标与游戏版本不匹配（例如模组只支持特定游戏版本）。

解决：

1. 收集 Mixin 日志。 使用 --mixin-log <modId> 启动：

   java -jar CopperLoader.jar -G mindustry.jar --mixin-log author:mod

2. 核对游戏版本。 确认游戏版本在模组支持范围内。

3. 反馈作者。 向模组作者反馈日志内容。

其他问题

需要更多日志

使用 -d（调试）或 --verbose（详细）参数启动，可以获得更多诊断信息：

java -jar CopperLoader.jar -G mindustry.jar -d

Android 端的报错

Android 端没有命令行启动方式，报错与解决办法见使用移动版 · 常见问题。与 dex 缓存相关的问题（构建失败、缓存缺失、模组不生效）另见 Android（ART）平台。

问题仍未解决

收集以下信息后，前往 Issues 反馈：

1. 操作系统与 Java 版本（java -version）；
2. 加载器版本（启动日志首行）；
3. 游戏 Jar 来源与版本；
4. 完整的启动日志（含错误堆栈）；
5. 模组文件清单。