Skip to content
Connected RailsConnected Rails

Troubleshooting

A mod that does not work rarely stops the simulator. Almost every mistake ends as a line in the log and a missing piece of content, so the first step is always to find that line.

  • The terminal. The simulator logs every loading warning and script error with a mod: prefix when the mods are read — at start, and again when a run starts after a toggle on the Mods page. Start it from a terminal (cargo run -p app, or train-sim) to see them. Problems found while a run is built — a name that does not resolve, a scenario event in an unknown module — are logged there too, without the prefix.
  • The Mods page of the main menu. Below the list, Warnings: shows the first few entries of the same log; Content: counts what was loaded, which tells you at a glance whether your new vehicle or scenario was read at all.
  • F9 in a run opens the same list and warnings as a panel.
  • Package installs from --install, or beside --dedicated or a run flag, report on stderr; one dropped onto the window reports on the Mods page.

The loader never gives up on the whole set because of one file:

  • A broken content file is a warning naming the file and the parser’s message. Every other file of the mod — and every other mod — still loads. The broken file’s content is simply absent.
  • A broken mod.ron hides the whole mod. Without a readable manifest there is no id to file anything under, so the mod does not appear in the list; the warning names the manifest.
  • A missing name falls back. A run asked for a vehicle, line or scenario that does not exist logs it and carries on: vehicle my_mod:my_loco not found — using the BR 101, line …: … — using the example line, scenario … not found. A run that starts is therefore no proof that your content was used.
  • A missing dependency is loaded around. The mod still loads, after the others, with mod my_mod: dependencies [...] missing or circular — loaded anyway, and the Mods page marks it requires: … (missing or switched off).
  • A script that raises an error is switched off after that first error, and the run continues without it. The error is in the log.

So the question is never “why did it crash” but “which warning did I miss”.

  • mod.ron is missing, misspelt, or does not parse — look for a warning naming it.
  • The folder is not directly below mods/. mods/my_mod/mod.ron is found, mods/downloads/my_mod/mod.ron is not.
  • The folder name starts with a dot; such directories are skipped on purpose.
  • The simulator was started from another directory. It reads mods/ in the working directory, or beside the binary if the working directory has none. The Mods page saying No mods installed is the sign.
  • The id is the manifest’s. References use id from mod.ron — the shipped mods/wolfsburg-demo/ has the id wolfsburg-demo, so its line is wolfsburg-demo:demo. Name the folder after the id; a folder named otherwise loads, but with a warning.
  • The name is the file stem, without folder and extension: scenarios/erste_fahrt.ron is my_mod:erste_fahrt.
  • The folder name is wrong. Only the folders listed in Mod structure are read, under exactly those names — scenarios/ and vehicles/ are plural, timetable/ is singular. A file in any other folder is not an error; it is just never read.
  • The mod is switched off. A switched-off mod is listed but not read.
  • Two mods have the same id. A copy of mods/example whose manifest still says id: "example" loads as a second example, and every file both have is reported as example:… defined twice — the later one wins. Change the id of the copy first.

If your content names another mod’s file — a scenario on example:beispielstrecke, a consist with example:br101_afb — put that mod into depends. Without it the reference still works on your machine, where the mod happens to be installed, but nothing warns a player who lacks it until the run falls back. Version requirements in the record form of depends produce warnings of their own (depends on … >=1.18.0, but … is 1.17.0); see Packaging and publishing.

A file that does not parse produces a warning with its path and the parser’s message, including the position in the file. Things to check there:

  • Strings are in double quotes.
  • An optional field takes Some(…): line: Some("example:beispielstrecke"), not line: "example:beispielstrecke".
  • Triggers, actions and wrapped values are written as in the reference pages and the example files, with their parentheses: Time(2.0), Message("…"), EdgeId(0).
  • Brackets match: (…) for a record, […] for a list, {…} for a map. A trailing comma is allowed.

The quickest repair is often to compare against the matching file in mods/example/, which is known to load.

The binary assets of the shipped mods are stored with Git LFS. A clone made without it has small text files in their place. The loader recognises such a pointer where a vehicle or character model should be and says …: … is a Git LFS pointer, not the model — run git lfs pull; --pack refuses to pack a mod that contains one. Run git lfs pull (setup: Git LFS).

Models, textures and sounds are named relative to the mods/ directory, starting with the mod’s folder name, and are loaded through the asset source mods://:

model: Some((
file: "example/assets/br101.gltf",
// …
)),

That file is read as mods://example/assets/br101.gltf. Typical mistakes:

  • The path starts at the mod (assets/br101.gltf) instead of at mods/.
  • The path names a folder other than the one the mod is in. A .crails package always installs into mods/<id>/, so a mod whose folder name differs from its id breaks here once it is installed from a package. The loader warns about such a folder (the folder should be named after the mod’s id); rename it and the asset paths with it.
  • Upper and lower case differ from the file on disk — it works on Windows and fails on Linux.

The editors catch what loading accepts but what will not behave:

  • Vehicle editor — the Checks section of the left panel reports figures that contradict each other, bindings that point at nothing and fields a vehicle of this kind cannot leave empty; its heading counts the errors and warnings. The block diagram lists its own bake findings, and a click on one selects the offending block. (Vehicle editor)
  • Route editor — the rule check flags what the line compiler will reject. Findings in the status bar counts them, and a click opens them under the module’s Checks. (Route editor)

In a checkout, cargo test -p mod-runtime loads every mod under mods/ and fails on any loading warning other than a missing LFS object — a quick way to check all of them at once (Testing and distribution).