错误码与诊断码
本页是 OmsiLaunch 0.1.0-beta3 英文原始页面 的译文。英文页面为规范文本：如有出入，以英文页面和代码为准。
本页是 PublicErrorCodes（src/OmsiLaunch.Api/PublicErrorCodes.cs）中每个代码的规范性参考：共 142 个 OL_E_ 错误码和一个 OL_W_ 警告，按目录类别分组，另附不属于错误的信息性诊断码。对于每个代码，本页说明当前代码在何处引发它、它的含义、它以何种方式到达您（抛出的异常、结果字段、诊断信息、控制平面回复或 CLI 信封）以及应如何处理。含义取自各引发位置；如果某个代码已定义但当前没有引发路径，本页会明确说明。
相关页面：公共 API、退出码、LaunchSpec、会话生命周期、事务与恢复、本地控制平面、运行时控制、会话配置档、永久插件。
代码如何到达您#
| 途径 | 含义 |
|---|---|
| 抛出 | 一个 Message 以该代码开头的异常（InvalidOperationException、IOException、TimeoutException、InvalidDataException、FileNotFoundException、ArgumentException、SessionProfileException）。CLI 从消息中提取代码并将其映射为退出码（CliProgram.Classify）。 |
| 计划诊断信息 | SessionPlan.Diagnostics 中的一个 LaunchDiagnostic；任何 OL_E_ 代码都会使 IsRunnable 为 false（CLI：计划 NOT RUNNABLE，退出码 1）。 |
| 会话诊断信息 | SessionStatus.Diagnostics 中的一个 LaunchDiagnostic；会话状态为 Failed（CLI 退出码 1）。OL_E_START_SESSION、OL_E_PROCESS_SUPERVISION 和 OL_E_RESTORE_FAILED 会在其消息中包装一个内部代码。 |
| 运行时结果 | RuntimeCommandResult.ErrorCode，同时 Succeeded = false。 |
| 运行时详情 | RuntimeCommandResult.ErrorCode = OL_E_RUNTIME_OPERATION_FAILED，具体代码作为 Values["detail"] 的第一个词元（另有 Values["exception"]）。插件侧所有 InvalidOperationException/ArgumentException 代码都通过这种方式呈现。 |
| 控制回复 | 本地控制平面回复（LocalControlResponse）的 ErrorCode。 |
| CLI 信封 | --json 信封（envelope）中的 error.code，或控制台上的 <code>: <message>；表中给出了退出码。 |
| 遥测 | 由主机映射为会话诊断信息的运行时事件名称。 |
Cli#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_CANCELLED | CliProgram.Classify | 有 OperationCanceledException 逸出（Ctrl+C 或客户端等待被取消）。 | CLI 信封，退出码 7 | 重试该命令。 |
OL_E_INTERNAL | CliProgram.Classify | 有不带 OL_E_ 代码的异常逸出：/spec JSON 格式错误、必需的 spec 成员为 null、意外故障。 | CLI 信封，退出码 10 | 阅读消息和 <root>\.omsilaunch\diagnostics\<sessionId>-host.log；修正输入；如果无法解释，请报告。 |
OL_E_TIMEOUT | CliProgram.Classify；LocalControlPlane.TryRequestAsync | 有不带代码的 TimeoutException 逸出；或者本地控制客户端已连接到所有者，但所有者未在超时内回复（所有者存在，因此不会报告为 OL_E_NO_ACTIVE_SESSION）。（邮箱超时则携带 OL_E_RUNTIME_REQUEST_TIMEOUT。） | CLI 信封、控制回复；来自 Classify 时退出码 5，控制回复时退出码 7 | 重试；检查 OMSI 和所有者是否有响应。 |
OL_E_WINDOWS_HOST_MISSING | CliProgram.RunAsync（/silent） | OmsiLaunchW.exe 不在 OmsiLaunch.exe 旁边。 | CLI 信封，退出码 7 | 重新安装该包。 |
OL_E_WINDOWS_HOST_START_FAILED | CliProgram.RunAsync（/silent） | 对 OmsiLaunchW.exe 调用 Process.Start 未返回进程。 | CLI 信封，退出码 7 | 检查包文件和权限；不带 /silent 运行以查看失败原因。 |
Compatibility#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_BUILD_VALIDATION_FAILED | OmsiLaunchService.ApplyTelemetry，收到 plugin.build.invalid 时 | 尽管主机已接受该可执行文件，插件在进程内的版本（build）检查（构建配置 Omsi23004_692EBFBF 加原生 VMT 探测）仍然失败，例如内存布局不同的、位于允许列表中的 Steam LAA 版本，或经过修补的 OMSI。 | 会话诊断信息（Failed） | 使用经运行时验证的版本；参见兼容性。 |
OL_E_UNSUPPORTED_BUILD | SessionPlanner（omsi.profile.OMSI23004 不可用） | Omsi.exe 缺失，或其大小/SHA-256 既不匹配构建配置指纹，也不在允许列表中。 | 计划诊断信息 | 安装受支持的 OMSI 2.3.004 版本。 |
OL_E_UNSUPPORTED_OPERATING_SYSTEM | SessionPlanner（runtime.current-windows-x64 不可用）；也由 CurrentWindowsX64Platform.ValidateCurrent 抛出，但服务不会调用该方法 | 不是 Windows 10 或更高版本，或者操作系统或主机进程不是 x64。 | 计划诊断信息（抛出时 CLI 退出码 3） | 在 64 位 Windows 10 或更高版本上运行。 |
OL_E_UNSUPPORTED_OS_ARCHITECTURE | 仅 CurrentWindowsX64Platform.ValidateCurrent | 操作系统或主机架构不是 x64。服务不会调用 ValidateCurrent；当前没有引发路径。 | 仅由该方法抛出（PlatformNotSupportedException） | 参见源代码 src/OmsiLaunch.Process/RuntimePlatform.cs。 |
Content#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_ENTRYPOINT_NOT_FOUND | LaunchValidation | NEW_MAP 未设置 EntrypointIdentity，且 PresentedEntrypointIndex 未设置或为负数。 | 计划诊断信息 | 设置 PresentedEntrypointIndex（/entrypoint-index:<n>）；使用 /list:entrypoints /map:<id> 查找入口点。 |
OL_E_ENTRYPOINT_REQUIRED | SessionPlanner（world.presented-entrypoint 不可用） | NEW_MAP 的地图已解析，但既没有呈现索引也没有标识。总是与 OL_E_ENTRYPOINT_NOT_FOUND 一同出现。 | 计划诊断信息 | 同上。 |
OL_E_HOF_NOT_FOUND | SessionPlanner | PlayerVehicle.Hof 不是已安装的 Vehicles\...\*.hof。 | 计划诊断信息 | 使用 /list:hofs 中的标识。（在此版本上，玩家车辆字段无论如何都不可运行。） |
OL_E_MAP_NOT_FOUND | LaunchValidation；SessionPlanner | 校验：NEW_MAP 的 MapIdentity 未设置，或其形式不是 maps\<dir>\global.cfg。规划器：该地图未安装。 | 计划诊断信息 | 使用 /list:maps 中的标识。 |
OL_E_NOT_FOUND | CliProgram.Classify | 有不带代码的 FileNotFoundException/DirectoryNotFoundException 逸出，例如带未知 /vehicle-scope 的 /list:repaints，或带未知 /map 的 /list:entrypoints。 | CLI 信封，退出码 6 | 更正标识。 |
OL_E_REPAINT_NOT_FOUND | SessionPlanner | PlayerVehicle.Repaint 不是该车型的 .cti 条目（仅在设置了 Model 时检查）。 | 计划诊断信息 | 使用 /list:repaints /vehicle-scope:<bus> 中的标识。 |
OL_E_SITUATION_MAP_NOT_FOUND | SessionPlanner | 所选 .osn 中引用的地图未安装。 | 计划诊断信息 | 安装该地图或选择其他情景。 |
OL_E_SITUATION_NOT_FOUND | LaunchValidation；SessionPlanner | SAVED_SITUATION 未设置 SituationIdentity，或该 .osn 未安装。 | 计划诊断信息 | 使用 /list:situations 中的标识。 |
OL_E_VEHICLE_NOT_FOUND | SessionPlanner | PlayerVehicle.Model 不是已安装的 Vehicles\...\*.bus。 | 计划诊断信息 | 使用 /list:vehicles 中的标识。 |
Installation#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_INSTALLATION_BUSY | InstallationLease.Acquire；OmsiLaunchService.RecoverPendingAsync；FileConfigurationTransaction.RestorePendingAsync | 安装租约（Local\OmsiLaunch.Installation.<hash>）被此登录会话中的另一个所有者持有，或者日志中记录的 OMSI 进程（PID + 创建时间 + 可执行文件路径；对于已过 HandoffCreated 但没有 PID 的日志，则为根目录下的任何 Omsi.exe）仍然存活。 | 启动：通过 OL_E_START_SESSION 作为会话诊断信息。恢复：抛出（InvalidOperationException / IOException）。CLI 退出码 7。 | 停止另一个所有者（session stop）或等待 OMSI 退出，然后重试或执行 /recover。 |
OL_E_INSTALLATION_NOT_FOUND | LaunchValidation | Installation.RootPath 为空。 | 计划诊断信息 | 传入安装目录。 |
OL_E_INSTALLATION_NOT_WRITABLE | SessionPlanner（transaction.exact-restore 不可用）；也包括 ValidateCurrent | 根目录不存在、具有只读属性，或没有 plugins\ 目录。 | 计划诊断信息 | 指向一个真实且可写的 OMSI 安装。 |
OL_E_PERMANENT_PLUGIN_HASH_MISMATCH | RuntimeArtifactSet.ValidateInstalled（规划和启动时） | 已安装的某个 plugins\OmsiLaunch.* 文件与 release-manifest.json 中的哈希不一致（没有清单时则与参考闭包不一致）。 | 计划诊断信息（计划不可运行，CLI 退出码 1）；仅当文件在规划与启动之间发生变化时，才通过 OL_E_START_SESSION 作为会话诊断信息 | 重新安装 OmsiLaunch 包，使 plugins\ 与清单一致。 |
OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE | RuntimeArtifactSet.ValidateInstalled（规划和启动时） | 清单中缺少某个必需插件文件的条目。 | 计划诊断信息；在与上文相同的竞态下，通过 OL_E_START_SESSION 作为会话诊断信息 | 重新安装该包。 |
OL_E_PERMANENT_PLUGIN_MISSING | RuntimeArtifactSet.ValidateInstalled（规划和启动时） | OMSI 安装中缺少某个必需的 plugins\OmsiLaunch.* 文件，或 release-manifest.json 中列出的某个 plugins/ 文件未安装。 | 计划诊断信息；在与上文相同的竞态下，通过 OL_E_START_SESSION 作为会话诊断信息 | 安装永久插件闭包（安装）。 |
OL_E_PLATFORM_CAPABILITY_MISSING | 仅 CurrentWindowsX64Platform.ValidateCurrent | CurrentPlatformSupported 为 false。服务不会调用该方法；当前没有引发路径。 | 仅由该方法抛出 | 参见源代码。 |
OL_E_RELEASE_MANIFEST_INVALID | ReleaseManifest.TryReadPluginHashes / ParsePluginHashes | release-manifest.json 为空、不是 JSON、没有 files 数组，或者含有以下条目：缺少 path/sha256、哈希不是 64 位十六进制数字、路径是带根路径、包含 :、包含空段、. 段或 .. 段，或同一路径列出两次（比较时不区分大小写，/ 与 \ 视为等同）。接受 UTF-8 BOM。 | 规划：包装在 OL_E_RUNTIME_ARTIFACT_MISSING 中；启动：通过 OL_E_START_SESSION | 重新安装该包。 |
InvalidArgument#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_INVALID_ARGUMENT | LaunchValidation；CliInput.Parse/Classify | 校验：在模式不是 Explicit 时设置了 Date.Value/Time.Value。CLI：未知参数、缺少值、整数或范围错误、/saved 与 /map//entrypoint 组合使用、未知命令路由，以及任何不带代码的 ArgumentException/FormatException。 | 计划诊断信息；CLI 信封，退出码 2 | 修正参数。 |
OL_E_INVALID_SETTING_VALUE | ConfigurationCatalog.CreatePatch（启动时） | 某个语义设置项的值超出范围、不是布尔值、不在允许的集合中，或格式错误（graphics.particles 需要四个字段）。规划时不会校验这些值。 | 通过 OL_E_START_SESSION 作为会话诊断信息 | 使用设置项表中的值。 |
OL_E_SETTING_NOT_WRITABLE | SessionPlanner；CliInput.BuildSpecAsync；BuildTransactionalOverlays | 该键存在但不可写（advanced.multithreadingCalculate、advanced.multithreadingTextureLoad、graphics.texture、graphics.textureFilter）。 | 计划诊断信息；CLI 退出码 2 | 删除该键。 |
OL_E_UNKNOWN_SETTING | SessionPlanner；CliInput.BuildSpecAsync；BuildTransactionalOverlays | 该键不在 ConfigurationCatalog 中。 | 计划诊断信息；CLI 退出码 2 | 使用目录中的键。 |
LaunchSpec#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_SPEC_INVALID | LaunchSpecJson.Parse | 根不是 JSON 对象，或反序列化未产生记录。 | 抛出（InvalidDataException），CLI 退出码 2 | 修正该文件（LaunchSpec）。 |
OL_E_SPEC_NOT_FOUND | LaunchSpecJson.LoadAsync | /spec 文件不存在。 | 抛出（FileNotFoundException），CLI 退出码 6 | 检查路径。 |
OL_E_SPEC_TOO_LARGE | LaunchSpecJson.LoadAsync | 文件超过 1 MiB。 | 抛出（InvalidDataException），CLI 退出码 2 | 缩小该文件。 |
OL_E_SPEC_UNKNOWN_PROPERTY | LaunchSpecJson.Validate | 某个成员不是该位置记录的公共属性；消息为 OL_E_SPEC_UNKNOWN_PROPERTY: $.Path.Name。 | 抛出（InvalidDataException），CLI 退出码 2 | 删除或重命名该成员。 |
LocalControl#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_CONTROL_COMMAND_UNKNOWN | 所有者处理程序（OwnerSession） | 该命令不是 session.status、session.events、session.stop，也不是带 operation 参数的 runtime.execute。 | 控制回复；CLI 退出码 7 | 使用受支持的命令。 |
OL_E_CONTROL_FAILED | CLI 客户端（ReportForwarded、CliEventWatch） | 所有者回复了 Ok = false，但没有错误码。 | CLI 信封，退出码 7 | 阅读消息；检查所有者的控制台/诊断信息。 |
OL_E_CONTROL_HANDLER_FAILED | LocalControlPlane.ServeAsync | 所有者的处理程序抛出了一个消息中不含 OL_E_ 代码的异常（例如会话已关闭），或处理程序的回复无法序列化。 | 控制回复 | 读取 session status；如果所有者已不存在，请重新启动所有者。 |
OL_E_CONTROL_MESSAGE_INVALID | LocalControlPlane（两端） | 长度前缀为负数或超过 64 KiB（包括过大的请求帧）、空帧、JSON null、没有 Command 的请求，或无法解码的 JSON。 | 控制回复 / CLI 信封 | 使用文档所述的协议（本地控制平面）。 |
OL_E_CONTROL_MESSAGE_TOO_LARGE | LocalControlPlane.TryRequestAsync（客户端） | 客户端自身序列化后的请求超过 64 KiB。错误报告给调用方；不会发送任何内容。 | 控制回复 / CLI 信封 | 缩小请求。 |
OL_E_CONTROL_RESPONSE_TOO_LARGE | LocalControlPlane.ServeAsync（所有者） | 所有者的回复无法装入 64 KiB 的帧。所有者以这个类型化错误作答，而不是丢弃回复。session.status 和 session.events 永远不会触发它：它们的事件历史会从最旧的开始裁剪以适应大小。 | 控制回复 / CLI 信封 | 重试；对于事件，请更频繁地读取。 |
OL_E_CONTROL_PROTOCOL | LocalControlPlane、TryRequestBoundAsync | 请求的 ProtocolVersion 不是 0.1；所有者回复无法解码或为空；所有者未回复就关闭了连接，或连接建立后中断；所有者未报告 SessionId。 | 控制回复 / CLI 信封 | 使客户端与所有者版本一致；读取 session status。 |
OL_E_CONTROL_SESSION_MISMATCH | 所有者处理程序 | session.stop 或 runtime.execute 没有携带与活动会话相同的 session_id。 | 控制回复；CLI 退出码 7 | 先读取 session.status 并绑定请求（CLI 会自动完成此操作）。 |
Other#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_PLAN_NOT_RUNNABLE | OmsiLaunchService.StartSessionAsync | 传入的计划 IsRunnable = false，或启动时的重新规划不可运行（Omsi.exe 已更改、内容被移除、插件闭包缺失）；消息列出当前的 OL_E_ 代码。 | 抛出（InvalidOperationException）；CLI 退出码 1 | 重新规划并修正列出的诊断信息。 |
Presentation#
均由 SessionVisualAssets（src/OmsiLaunch.Core/SessionVisualAssets.cs）引发。在规划时，它们被包装在 OL_E_SESSION_PRESENTATION_INVALID 中（消息携带该代码）；在启动时，它们通过 OL_E_START_SESSION 呈现。
| 代码 | 含义 / 典型原因 | 处理方法 |
|---|---|---|
OL_E_ITX_PROFILE_INVALID | .itx 文件为空、非空白行数为奇数，或某个 URL 行不是绝对的 http/https URL。 | 使用 URL/目标成对的行。 |
OL_E_ITX_PROFILE_MISSING | OverrideProfilePath（相对于进程工作目录解析）不存在。以 FileNotFoundException 抛出。 | 传入一个存在的 .itx 路径。 |
OL_E_ITX_PROFILE_REQUIRED | InternetTextures.Mode 为 Override，但没有 OverrideProfilePath。抛出时 CLI 退出码 2。 | 提供 /internet-textures-profile:<file.itx>。 |
OL_E_ITX_TARGET_OUTSIDE_TEXTURE_PATH | 某个目标行是带根路径、包含 ..、以 \ 开头、解析到安装之外、缺少 Texture\ 路径组成部分，或穿越了联接点/符号链接。 | 使用 Texture\... 相对目标。 |
OL_E_SPLASH_ASSET_DIRECTORY_MISSING | CustomAssetDirectory 不存在。 | 修正该目录。 |
OL_E_SPLASH_ASSET_MISSING | 资源目录中缺少 ENG.bmp 或 <LANG>.bmp，或者在初始化 .omsilaunch\assets\splash 时缺少包内的 assets\splash\<LANG>.bmp。 | 提供这些 BMP / 重新安装该包。 |
OL_E_SPLASH_FORMAT_UNSUPPORTED | 某个启动画面 BMP 不是 640×480 的 24 位 BM 位图。 | 转换该图像。 |
Process#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_PROCESS_CLEANUP_FAILED | OmsiLaunchService（启动失败和监管器故障路径） | 在错误清理期间终止或等待 OMSI 时抛出异常；其后附有内部消息。 | 会话诊断信息（添加到 Failed 会话） | 确保没有残留的 Omsi.exe，如果存在待处理的日志，则执行 /recover。 |
OL_E_PROCESS_CREATION_TIME_FAILED | CurrentWindowsX64Platform.StartAsync | 在 CreateProcessW 之后立即调用的 GetProcessTimes 失败（Win32=<code>）；该进程被终止。 | 通过 OL_E_START_SESSION 作为会话诊断信息 | 重试；检查杀毒软件/权限。 |
OL_E_PROCESS_EXITED_EARLY | OmsiLaunchService.SuperviseAsync | OMSI 在 gameplay.entered 之前退出（崩溃、OMSI 错误对话框被关闭、窗口被关闭）。 | 会话诊断信息（Failed）；执行还原 | 检查 OMSI 自身的日志和 logfile.txt；查看 RuntimeEvents 中的最后一个插件事件。 |
OL_E_PROCESS_START_FAILED | CurrentWindowsX64Platform.StartAsync | CreateProcessW 失败（消息中含 Win32=<code>）。 | 通过 OL_E_START_SESSION 作为会话诊断信息 | 解决该 Win32 错误（文件缺失、访问被拒绝、策略）。 |
OL_E_PROCESS_SUPERVISION | OmsiLaunchService.SuperviseAsync | 监管器循环抛出异常（遥测读取、进程等待/终止、日志写入）；OMSI 被终止并尝试还原。 | 会话诊断信息（Failed） | 阅读内部消息和主机日志。 |
OL_E_PROCESS_TERMINATE_FAILED | CurrentWindowsX64Platform.Terminate | TerminateProcess 失败（Win32=<code>）。 | 出现在 OL_E_PROCESS_SUPERVISION / OL_E_PROCESS_CLEANUP_FAILED 消息中 | 手动终止 OMSI，然后执行 /recover。 |
OL_E_PROCESS_WAIT_FAILED | CurrentWindowsX64Platform.WaitForExitAsync | 对进程句柄调用 WaitForSingleObject 失败。 | 出现在 OL_E_PROCESS_SUPERVISION / OL_E_PROCESS_CLEANUP_FAILED 消息中 | 同上。 |
Runtime#
“运行时详情”是指 ErrorCode = OL_E_RUNTIME_OPERATION_FAILED，且代码位于 Values["detail"] 的开头。
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_CAMERA_PRESET_FAMILY_UNSUPPORTED | OmsiCameraLockWriter | camera.lock 带有 preset，而 family 为 2（外部）或 3（地图）；预设仅适用于司机（0）和乘客（1）。 | 运行时详情 | 省略 preset 或使用 family 0/1。 |
OL_E_DATE_TIME_APPLY_FAILED | LaunchValidation | Date/Time 模式为 Explicit 但没有值，或各组成部分超出范围。该名称是历史遗留；它是一个规划时的校验错误。 | 计划诊断信息 | 修正该值（并注意在此版本上显式日期/时间不可运行）。 |
OL_E_MAKEVEHICLE_BUS_NOT_FOUND | CurrentRuntimeControl.MakeBasicRoadVehicle | road-vehicles.spawn：.bus 路径在 OMSI 工作目录下不存在（在原生调用之前检查，以免 OMSI 替换为后备车辆）。 | 运行时详情 | 使用 vehicles list//list:vehicles 中的标识。 |
OL_E_MAKEVEHICLE_DELTA_MULTIPLE | 同上 | 原生 MakeVehicle 使道路车辆集合的变化超过一个对象。 | 运行时详情（native_status，消息中含计数） | 报告；已创建的对象会保留到会话结束。 |
OL_E_MAKEVEHICLE_DELTA_ZERO | 同上 | 集合没有变化；OMSI 静默拒绝了该车辆。 | 运行时详情 | 检查 .bus 文件；尝试其他车型。 |
OL_E_MAKEVEHICLE_NATIVE_FAILED | 同上 | 任何其他非零原生状态。 | 运行时详情 | 附上消息中的计数进行报告。 |
OL_E_PLACE_RANDOM_BUS_FAILED | CurrentRuntimeControl.PlaceRandomBus | 已建立构建配置的 PlaceRandomBus 调用返回了失败状态。 | 运行时详情 | 待游戏过程稳定后重试；报告。 |
OL_E_RUNTIME_ARGUMENT_REQUIRED | PublicCapabilityRegistry.ValidateRuntimeArguments；插件侧检查（time.set 没有 hour/minute/second；camera.set 没有 family/field_of_view；camera.lock 没有可解析的 family；车辆/曲线操作） | 某个必需参数缺失或为空。 | 运行时结果（注册表；CLI 退出码 2）或运行时详情（插件） | 提供该参数（运行时控制）。 |
OL_E_RUNTIME_ARTIFACT_MISSING | OmsiLaunchService.PlanSessionAsync | 无法加载 OmsiLaunchRuntimePaths 中给出的插件闭包参考目录/文件或原生桥（可能包装 OL_E_RELEASE_MANIFEST_INVALID）。 | 计划诊断信息 | 从完整的包中运行。 |
OL_E_RUNTIME_BASELINE_UNAVAILABLE | RuntimeBatch（/runtime-write-batch，INTERNAL 测试工具） | 基线 time.read/camera.read 失败，因此跳过了写入测试。 | 仅批处理产物 | 不面向用户。 |
OL_E_RUNTIME_BUS_IDENTITY_INVALID | CurrentRuntimeControl.ValidateBasicBusIdentity | model 为空、长度超过 240 个字符、包含 NUL 或 ..、不以 Vehicles\ 开头，或不以 .bus 结尾。 | 运行时详情 | 传入 Vehicles\<dir>\<file>.bus。 |
OL_E_RUNTIME_CHANNEL_BUSY | 无（为兼容性而保留） | 不再发出。早期版本在已取消的请求仍留在槽中时会引发它；现在请求的每条终止路径都会重置该槽，并且在新请求开始时发现的残留请求或响应会被清除。 | — | — |
OL_E_RUNTIME_CHANNEL_CLOSED | OmsiLaunchService.LiveSession.RequestRuntimeAsync | 由于会话正在结束，邮箱已被释放。 | 抛出（InvalidOperationException） | 无需处理；会话已结束。 |
OL_E_RUNTIME_CHANNEL_STATE_INVALID | CurrentRuntimeCommandStore.RequestAsync | 邮箱槽中的状态值不是空闲、已请求或已响应（数据损坏）。该槽被重置并引发此错误；下一个请求可正常工作。 | 抛出（InvalidDataException） | 重试；如果持续出现，请报告。 |
OL_E_RUNTIME_CONSTANTS_UNAVAILABLE | OmsiRuntimeReaders | 车辆的常量块指针为 null。 | 运行时详情 | 该车辆没有常量；无需处理。 |
OL_E_RUNTIME_CONSTANT_NOT_FOUND | OmsiRuntimeReaders | name 不在车辆的常量表中。 | 运行时详情 | 先列出常量。 |
OL_E_RUNTIME_CREATED_OBJECT_INVALID | OmsiRuntimeReaders.RegisterRoadVehicleHandleAsync | 生成操作创建的对象的 VMT 位于 OMSI 映像范围之外。 | 运行时详情 | 报告。 |
OL_E_RUNTIME_CREATED_OBJECT_NOT_IN_COLLECTION | 同上 | 创建的对象不在道路车辆集合中。 | 运行时详情 | 报告。 |
OL_E_RUNTIME_CURVE_DEGENERATE | OmsiRuntimeReaders.EvaluateRoadVehicleCurveAsync | 两个相邻的曲线点具有相同的 X。 | 运行时详情 | 车辆曲线的内容问题。 |
OL_E_RUNTIME_CURVE_EMPTY | 同上 | 曲线没有点。 | 运行时详情 | 同上。 |
OL_E_RUNTIME_CURVE_INVALID | 同上 | 曲线中没有任何分段包含 x。 | 运行时详情 | 在曲线的定义域内求值。 |
OL_E_RUNTIME_CURVE_NOT_FOUND | 同上 | name 未知，或其函数指针为 null。 | 运行时详情 | 先列出曲线。 |
OL_E_RUNTIME_HOF_UNAVAILABLE | OmsiRuntimeReaders.ReadRoadVehicleHofsAsync | 车辆定义指针为 null。 | 运行时详情 | 句柄指向一个没有定义数据的车辆。 |
OL_E_RUNTIME_INSTALLATION_INCOMPLETE | CliProgram.RunAsync（所有者模式） | 可执行文件旁缺少 plugins\OmsiLaunch.Plugin.opl 或 plugins\OmsiLaunch.Native.x86.dll。 | CLI 信封，退出码 7 | 重新安装该包。 |
OL_E_RUNTIME_OBJECT_HANDLE_REQUIRED | CurrentRuntimeControl | road-vehicle.read、human.read、vehicle.variables.list、vehicle.string-variables.list、vehicle.constants.list、vehicle.curves.list 的 handle 缺失或为空（注册表通常会先以 OL_E_RUNTIME_ARGUMENT_REQUIRED 拒绝这些请求）。 | 运行时详情 | 提供句柄。 |
OL_E_RUNTIME_OBJECT_HANDLE_STALE | OmsiRuntimeReaders | 句柄未知、对象已离开集合、地址代次已推进，或者由于地址被重用，对象指纹（VMT + 定义/车型标识）已改变。残留盲区：在两次列表读取之间，同一类别和车型的对象在同一地址被重新创建。 | 运行时详情 | 再次运行 road-vehicles.list/humans.list 并使用新句柄。 |
OL_E_RUNTIME_OPERATION_FAILED | CurrentRuntimeControl.Execute；CurrentRuntimeCommandMailbox.TryDispatch；D3DRuntimeApi 后备路径 | 通用的插件侧失败包装；Values["detail"] 保存消息（通常是更具体的代码），Values["exception"] 保存异常类型。在邮箱调度器内从某个操作中逸出的异常也会以此代码（不带值）作答，而不是让请求得不到回复。 | 运行时结果 | 阅读 detail。 |
OL_E_RUNTIME_OPERATION_UNAVAILABLE | CurrentRuntimeControl.Execute | 插件没有注册表所允许的某个操作的实现（注册表/插件版本漂移）。 | 运行时详情 | 重新安装版本一致的包。 |
OL_E_RUNTIME_OPERATION_UNKNOWN | PublicCapabilityRegistry.ValidateRuntimeArguments | 该操作不在 PublicRuntimeOperationIds 中，包括所有 internal.* 操作。在查找会话之前检查。 | 运行时结果；控制回复；CLI 退出码 2 | 使用公共操作 ID。 |
OL_E_RUNTIME_PLAYER_VEHICLE_UNAVAILABLE | OmsiCameraLockWriter | camera.lock 带有 preset，但没有玩家车辆（无头会话没有玩家车辆）。重新应用失败时，也会作为 camera.lock.degraded 事件的 code 报告。 | 运行时详情 / 运行时事件 | 不带预设进行锁定，或使用有玩家车辆的会话。 |
OL_E_RUNTIME_PROTOCOL_MISMATCH | D3DRuntimeApi | 某个成功的 D3D 结果没有值，或设备状态字符串未知。 | 抛出（OmsiRuntimeException） | 使主机与插件版本一致。 |
OL_E_RUNTIME_REQUEST_ID_REUSED | CurrentRuntimeCommandStore.RequestAsync | 槽中存有一个过期响应，其请求 ID 与新请求相同。该过期响应在引发错误之前被清除。 | 抛出（InvalidOperationException） | 使用严格递增的请求 ID。 |
OL_E_RUNTIME_REQUEST_TIMEOUT | CurrentRuntimeCommandStore.RequestAsync | 在 timeout 内没有响应；该槽被重置，迟到的响应会被丢弃。 | 抛出（TimeoutException）；CLI 退出码 5 | 使用更长的超时重试；检查 OMSI 是否被阻塞（模态对话框、加载中）。 |
OL_E_RUNTIME_RESPONSE_INVALID | CurrentRuntimeCommandStore | 响应信封已损坏、长度错误（负数、零或大于槽）、会话 ID 不属于本会话，或请求 ID 不同。该槽在引发错误之前被重置，因此下一个请求可正常工作。 | 抛出（InvalidDataException） | 重试；如果持续出现，请报告。 |
OL_E_RUNTIME_RESPONSE_TOO_LARGE | CurrentRuntimeCommandMailbox.TryDispatch | 序列化后的结果超过 64 KiB 邮箱。有界列表结果（带有 returned_count 和 truncated 的结果）则会被缩短以适应大小（文档审计 BUG-05）；实际上，该代码仍可能由不属于有界列表的 timetable.logs.read 触发。 | 运行时结果 | 使用范围更窄的操作（例如在庞大的集合上用 road-vehicles.read 代替 road-vehicles.list）。 |
OL_E_RUNTIME_SCRIPT_OBJECT_UNAVAILABLE | OmsiRuntimeReaders | 车辆的脚本定义或状态指针为 null。 | 运行时详情 | 该车辆没有脚本对象。 |
OL_E_RUNTIME_SESSION_MISMATCH | OmsiLaunchService.ExecuteRuntimeAsync；CurrentRuntimeCommandStore；插件邮箱 | RuntimeCommand.SessionId 与句柄的会话 ID 不同（由主机抛出），或者某个请求到达了绑定到另一会话的插件（由插件作为类型化结果返回）。 | 抛出（InvalidOperationException）/ 运行时结果 | 使用 session.SessionId 构建命令。 |
OL_E_RUNTIME_SETTING_NOT_PERSISTENT | CurrentRuntimeControl.SetWeather | weather.set 始终被拒绝：OMSI 会在下一次天气更新时覆盖已建立构建配置的天气字段，因此写入无法作为语义变更报告。 | 运行时结果 | 无；weather.set 为 UNAVAILABLE。 |
OL_E_RUNTIME_SETTING_UNAVAILABLE | OmsiWeatherWriter | 未知的天气字段名称。由于 weather.set 更早被拒绝，目前无法触发。 | 运行时详情（已定义） | 参见源代码 src/OmsiLaunch.Interop/OmsiWeatherWriter.cs。 |
OL_E_RUNTIME_STRING_VARIABLE_NOT_FOUND | OmsiRuntimeReaders | name 不在字符串变量表中。 | 运行时详情 | 先列出字符串变量。 |
OL_E_RUNTIME_VALUE_INVALID | OmsiWeatherWriter.ParseBoolean | 某个天气布尔值不是 true/false/1/0。目前无法触发（见上文）。 | 运行时详情（已定义） | 参见源代码。 |
OL_E_RUNTIME_VALUE_OUT_OF_RANGE | CurrentRuntimeControl、OmsiCameraWriter、OmsiCameraLockWriter、OmsiRuntimeReaders、OmsiWeatherWriter | time.set：hour 0..23、minute 0..59、second 0..59.999；camera.set：family 0..3、field_of_view 10..170；camera.lock：preset 不是整数、family 0..3、preset 0..255；road-vehicles.place-random：ai_type 0..255、group/type/tour/line 0..65535（type 可以为 -1）、scheduled 0..1；vehicle.variable.set：value 不是有限值；vehicle.curve.evaluate：x 不是有限值。 | 运行时详情 | 使用范围内的值。 |
OL_E_RUNTIME_VARIABLE_NOT_FOUND | OmsiRuntimeReaders | name 不在数值变量表中。 | 运行时详情 | 先列出变量。 |
OL_E_RUNTIME_VARIABLE_UNAVAILABLE | OmsiRuntimeReaders | 变量槽或值地址为 null。 | 运行时详情 | 该变量未在此车辆上实例化。 |
OL_E_TIME_APPLY_FAILED | CurrentRuntimeControl.SetTime | 时钟标量已写入，但已建立构建配置的原生 SetTime 调用返回失败。 | 运行时详情 | 重试；用 time.read 读回。 |
RuntimeD3D#
均由 CurrentRuntimeControl 引发（原生状态的 ThrowD3D 映射；detail 携带操作和 HRESULT，native_status 携带数值状态）。途径：运行时结果，代码位于 ErrorCode 中；D3DRuntimeApi 将其作为 OmsiRuntimeException 重新抛出。
| 代码 | 原生状态 / 原因 | 处理方法 |
|---|---|---|
OL_E_D3D_DEVICE_LOST | 8：Direct3D 设备丢失。 | 等待 d3d.restored；重新创建纹理（代次已改变）。 |
OL_E_D3D_INVALID_ARGUMENT | 14：width、height、level、x、y、format 或 handle 缺失或无效（范围：width/height 1..4096，levels 0..16，level 0..15，x/y 0..4095）。 | 修正参数。 |
OL_E_D3D_INVALID_PIXEL_BUFFER | pixels_base64 不是有效的 Base64，或超过 48 KiB。 | 发送更小的矩形。 |
OL_E_D3D_INVALID_TEXTURE_FORMAT | 6，或未知的 format 名称（有效值：A8R8G8B8、X8R8G8B8、R5G6B5、X1R5G5B5、A1R5G5B5、A4R4G4B4、A8、L8、A8L8）。 | 使用列出的格式。 |
OL_E_D3D_NATIVE_CALL_FAILED | 任何其他状态；HRESULT 位于 detail 中。 | 附上 HRESULT 进行报告。 |
OL_E_D3D_NOT_READY | 7：设备尚未就绪（第一帧之前或正在停止时）。 | 在 d3d.ready 之后重试。 |
OL_E_D3D_RESET_IN_PROGRESS | 9：设备重置正在进行。 | 在 d3d.restored 之后重试。 |
OL_E_D3D_RESOURCE_RELEASED | 13：纹理句柄已被释放。 | 不要重用已释放的句柄。 |
OL_E_D3D_STALE_RESOURCE_HANDLE | 12：句柄属于之前的设备代次；或句柄字符串不是 d3dtex-<session>-<hex> / 为零。 | 重新创建纹理。 |
Session#
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_CAPABILITY_UNAVAILABLE | SessionPlanner；ApplyTelemetry，收到 plugin.request.unsupported 时 | 规划：请求了 LastMapState、EntrypointIdentity、日期/时间/年份模式、天气模式、玩家车辆字段或输入文档（Requested capability unavailable: <name>）。遥测：插件拒绝了交接（对于可运行的计划不会发生）。 | 计划诊断信息；会话诊断信息 | 移除不受支持的请求（已知限制）。 |
OL_E_HEADLESS_ARM_FAILED | ApplyTelemetry，收到 headless.arm.failed 时 | 插件无法在 OMSI 中挂载一次性的无头启动钩子。 | 会话诊断信息（Failed） | 验证版本；报告。 |
OL_E_NO_ACTIVE_SESSION | CLI 客户端（ReportForwarded、CliEventWatch） | 该安装的控制管道上没有所有者应答（没有会话，或所有者仍在启动/校验中）。 | CLI 信封，退出码 4 | 启动一个会话，或等待其进入 Running。 |
OL_E_PLUGIN_NOT_LOADED | SuperviseAsync | 在 plugin.started 之前 StartupTimeoutSeconds 已耗尽（OMSI 未加载 plugins\OmsiLaunch.Plugin.opl，或在插件初始化之前卡住）。 | 会话诊断信息（Failed） | 检查插件闭包、plugins\OmsiLaunch.Plugin.opl 和 OMSI 的 logfile.txt。 |
OL_E_PLUGIN_PROTOCOL_MISMATCH | ApplyTelemetry，收到 plugin.handoff.invalid 或无法解析的遥测 JSON 时 | 插件无法读取/验证启动交接（版本 3/4，SHA-256），或发送了无效的遥测。 | 会话诊断信息（Failed） | 使主机与插件版本一致（重新安装该包）。 |
OL_E_SESSION_ALREADY_ACTIVE | CliProgram.RunAsync | 已有一个所有者为此安装应答 session.status。 | CLI 信封，退出码 7 | 使用客户端命令（session status、session stop、运行时命令）。 |
OL_E_SESSION_NOT_RUNNING | OmsiLaunchService.ExecuteRuntimeAsync | 会话状态不是 Running。 | 抛出（InvalidOperationException） | 先调用 WaitForAsync(session, SessionState.Running, ...)。 |
OL_E_SESSION_PRESENTATION_INVALID | SessionPlanner | 无法构建启动画面/ITX 计划；消息携带呈现类代码。 | 计划诊断信息 | 参见 Presentation。 |
OL_E_SESSION_START_FAILED | WindowsHost.ShowFailure（OmsiLaunchW 对话框） | 当启动计划不可运行或会话未进入游戏过程，且不存在 OL_E_ 诊断信息时显示的后备代码。 | 仅消息框 | 阅读 .omsilaunch\diagnostics。 |
OL_E_SITUATION_LOAD_FAILED | ApplyTelemetry，收到 world.situation.failed 时 | 原生的已保存情景启动返回失败（事件中含 native_status）。 | 会话诊断信息（Failed） | 检查该 .osn 及其地图。 |
OL_E_STARTUP_TIMEOUT | SuperviseAsync | 插件已启动，但未在 StartupTimeoutSeconds 内进入 Running。 | 会话诊断信息（Failed） | 对于大型地图，增大 /startup-timeout；检查 RuntimeEvents 中的最后一个世界事件。 |
OL_E_START_SESSION | OmsiLaunchService.StartAsync | 启动路径中的任何异常；消息即内部消息（通常以内部代码开头）。 | 会话诊断信息（Failed） | 根据内部代码处理。 |
OL_E_WORLD_START_FAILED | ApplyTelemetry，收到 world.failed 时 | 原生 NEW_MAP 启动返回失败（事件中含 native_status）。 | 会话诊断信息（Failed） | 检查地图、入口点索引和 OMSI 的日志。 |
SessionProfile#
均由 SessionProfileCompiler（src/OmsiLaunch.Core/SessionProfiles.cs）或 CliInput 引发，以 SessionProfileException（带有 Code 的 IOException）抛出，CLI 退出码 2。参见会话配置档。
| 代码 | 含义 / 典型原因 | 处理方法 |
|---|---|---|
OL_E_SESSION_PROFILE_ASSET_MISSING | 预设的启动画面 assets 目录或网络纹理 profile 文件在包内不存在。 | 添加该资源。 |
OL_E_SESSION_PROFILE_INVALID | 结构或限制违规：超过 256 KiB、根映射不是恰好一个、使用了 YAML 锚点、未知键、缺少必需键、需要标量处为非标量、id 与目录名不同、预设不在 1..5 范围内或 index 重复、超时不是正数、不受支持的天气/启动画面/网络纹理模式、日期/时间不是 explicit、无效的 YAML、数字/日期解析错误。 | 根据消息修正 YAML。 |
OL_E_SESSION_PROFILE_MAP_MISMATCH | compatibility.maps 非空，且不包含所选地图（NEW_MAP）或所选情景的地图（SAVED_SITUATION）。 | 选择兼容的世界。 |
OL_E_SESSION_PROFILE_NOT_FOUND | <root>\.omsilaunch\session-profiles\<id>\profile.yaml 不存在。 | 检查 ID。 |
OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT | 某个显式 CLI 参数指向了所选配置档/预设所拥有的字段。 | 去掉该参数或选择其他预设。 |
OL_E_SESSION_PROFILE_PATH_ESCAPE | ID 包含 \、/、: 或 ..；或者某个资源路径是带根路径、逃逸出包，或穿越了联接点/符号链接。 | 使路径保持在包内。 |
OL_E_SESSION_PROFILE_PRESET_NOT_FOUND | /predefined-profile-index 缺失、超出 1..5，或未由该配置档声明。 | 使用已声明的预设索引。 |
OL_E_SESSION_PROFILE_SCHEMA_UNSUPPORTED | schema 不是 omsilaunch.session-profile/v1。 | 使用受支持的 schema。 |
OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE | 某个预设设置项键已知但不可写。 | 删除该键。 |
OL_E_SESSION_PROFILE_SETTING_UNKNOWN | 某个预设设置项键不在目录中。 | 使用目录中的键。 |
Transaction#
参见事务与恢复。
| 代码 | 引发位置 | 含义 / 典型原因 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_E_CLOSECHECK_REMOVE_FAILED | OmsiLaunchService.RemoveStaleClosecheck | 执行 File.Delete 之后，过期的 closecheck 仍然存在。 | 通过 OL_E_START_SESSION 作为会话诊断信息 | 手动删除 <root>\closecheck（权限问题）。 |
OL_E_RECOVERY_ABSENT_OWNERSHIP_MISMATCH | FileConfigurationTransaction.RestoreAsync | 某个在会话之前不存在的路径现在含有与会话所应用内容不同的内容；它不会被删除，事务日志会被保留。 | 抛出（IOException）；出现在 OL_E_RESTORE_FAILED / OL_E_START_SESSION 中；CLI 退出码 8 | 检查该文件；删除或移走它，然后执行 /recover。 |
OL_E_RECOVERY_ABSENT_OWNERSHIP_UNVERIFIED | RestoreAsync（指纹机制之前的事务日志） | 对于一个原本不存在且非删除类的路径，事务日志中没有已应用内容的指纹，因此无法证明所有权。在会话启动时，恢复会被推迟，并使用本次会话计划的字节重试；通过 RecoverPendingAsync 调用时则会抛出。 | 抛出（IOException）；CLI 退出码 8 | 使用相同的 spec 启动会话（以提供这些字节），或检查并删除该文件，然后执行 /recover。 |
OL_E_RECOVERY_BACKUP_CORRUPT | RestoreAsync | 某个备份的 SHA-256 与事务日志中记录的快照不一致；不会写入任何内容。 | 抛出；出现在 OL_E_RESTORE_FAILED 中；CLI 退出码 8 | 从您自己的备份中还原该文件；只有在确定无误时才删除事务日志。 |
OL_E_RECOVERY_JOURNAL_MISSING | RestoreAsync | 内存中存在快照，但 journal.json 已不存在（在会话期间被删除）。 | 抛出；出现在 OL_E_RESTORE_FAILED 中 | 手动核实会话文件。 |
OL_E_RECOVERY_JOURNAL_REMOVE_FAILED | FileConfigurationTransaction.RemoveJournal | 删除后 journal.json 仍然存在（还原本身已成功并经过校验）。 | 抛出；出现在 OL_E_RESTORE_FAILED 中；CLI 退出码 8 | 删除 <root>\.omsilaunch\journal.json（权限问题），或再次运行 /recover（幂等）。 |
OL_E_RESTORE_DEFERRED | OmsiLaunchService（启动失败 / 监管器） | 无法确认 OMSI 已退出，因此在它可能仍在使用这些文件时没有替换它们；事务日志被保留。 | 会话诊断信息（Failed） | 在 Omsi.exe 退出后运行 /recover（或由下一次启动自动恢复）。 |
OL_E_RESTORE_FAILED | OmsiLaunchService（启动失败 / 监管器） | RestoreAsync 抛出异常；消息携带内部代码；事务日志被保留。 | 会话诊断信息（Failed）；从 /recover 抛出时 CLI 退出码 8 | 根据内部代码处理，然后执行 /recover。 |
Warning#
| 代码 | 引发位置 | 含义 | 途径 | 处理方法 |
|---|---|---|---|---|
OL_W_RESTORE_FOREIGN_FILE_RETAINED | FileConfigurationTransaction.RestoreAsync | 某个会话删除类路径（ITX 目标、Texture\standard.ipr、closecheck）在会话之前不存在、现在存在，但在此事务日志下从未启动过 OMSI 进程，因此该文件不可能是会话的副产物。它会被保留并报告（消息 = 相对路径，Data["sha256"]）；事务仍会完成。 | 会话诊断信息 / RecoveryStatus.Diagnostics（不影响状态） | 检查该文件；如果不需要，请自行删除。 |
非错误诊断码#
| 代码 | 发出者 | 消息 / 数据 | 含义 |
|---|---|---|---|
process.started | OmsiLaunchService.LiveSession.Attach | 消息 = PID；Data["thread_id"]、Data["creation_utc"]（ISO 8601） | Omsi.exe 已创建，其标识已记录。会话诊断信息。 |
closecheck.stale-removed | OmsiLaunchService.RemoveStaleClosecheck | 消息 = 被删除文件的 SHA-256 | 会话之前已存在的 closecheck 被永久删除（SuppressStaleClosecheckWarning = true）。会话诊断信息。 |
restore.session-artifact-removed | FileConfigurationTransaction.RestoreAsync | 消息 = 相对路径；Data["sha256"] | 在进程已启动的会话期间，某个会话删除类路径被 OMSI 重新创建；为还原其原本不存在的状态，它已被删除。会话诊断信息 / RecoveryStatus.Diagnostics。 |
plugin.integrity.reference | OmsiLaunchService.PlanSessionAsync | 消息 = manifest 或 self | 永久插件校验所使用的参考。计划诊断信息。 |
session_profile.selected | SessionPlanner | 消息 = 配置档 ID；Data["session_profile.id|name|version|author|preset_id|preset_index|preset_name|path"] | 由会话配置档编译而成的会话的来源信息。计划诊断信息。 |
运行时事件名称（RuntimeEvent.Type，不属于诊断信息）列于会话生命周期中。