Troubleshooting

Common Issues

Game stuck on login screen:

The TMNF account must be an online account. If your account is offline:

Start the game without TMInterface and create an online account
Set your USERNAME in the .env file to that online account

FileNotFoundError: Python_Link.as

The plugin wasn’t copied to the correct location. Run:

# Windows
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\Documents\TMInterface\Plugins"
Copy-Item "trackmania_rl\tmi_interaction\Python_Link.as" "$env:USERPROFILE\Documents\TMInterface\Plugins\"

# Linux
mkdir -p ~/Documents/TMInterface/Plugins
cp trackmania_rl/tmi_interaction/Python_Link.as ~/Documents/TMInterface/Plugins/

CUDA not available

Ensure NVIDIA driver 525+ is installed: nvidia-smi
Check PyTorch installation: python -c "import torch; print(torch.cuda.is_available())"
Reinstall PyTorch: uv sync --reinstall or follow PyTorch installation guide

TorchRL warning about C++ binaries

Ensure you’re using PyTorch 2.7+ with matching TorchRL version. The uv sync command installs compatible versions automatically.

Map not loading

Ensure map files are NOT in OneDrive or cloud storage directories
Verify map path in the map_cycle.entries section of your config YAML matches actual location
Check that map file exists in ~/Documents/TrackMania/Tracks/Challenges/

Low FPS / Slow training

Increase gpu_collectors_count in the performance section of the config YAML
Increase running_speed (up to 200x real-time)
Lower game graphics settings and resolution
Close unnecessary background applications

Memory issues

Reduce memory_size_schedule in the memory section
Reduce gpu_collectors_count in the performance section
Reduce batch_size in the training section
Check RAM usage with Task Manager / htop

Optimizer state / checkpoint after changing ``nn.*.freeze``

If you change which parameters are frozen (nn.vis.freeze, nn.decoder.advantage.freeze, etc.; see RL parameter freeze in Configuration Guide), the set of tensors in the Adam optimizer state no longer matches the network. The learner may log that it starts a fresh optimizer. To avoid confusing resumes, delete optimizer1.torch / scaler.torch under save/<run_name>/ when the trainable parameter set changes, or start a new run_name.

Agent gets stuck or doesn’t progress

Verify virtual checkpoint file (.npy) is correctly generated
Check cutoff_rollout_if_no_vcp_passed_within_duration_ms timeout
Increase exploration (higher epsilon in the exploration section)
Verify reference line covers the entire track

Cars stop moving during training (Window Focus Issue) 🆕

Symptoms: Cars “twitch” at start but don’t move forward. Clicking on a window makes it work again.

Cause: TMInterface requires window focus to process inputs, even with unfocused_fps_limit false.

Solution: This is now automatically fixed in the code. The game window receives focus once per map load, which is sufficient. No manual intervention needed.

Technical details:

Window focus is set automatically when loading a new map
For multiple instances (8+), focus is managed to avoid “focus war”
Minimal performance impact (<0.01%)
Works correctly with map cycling

If issue persists:

Check that windows are not minimized (game pauses when minimized)
With multiple maps, ensure smooth transitions between maps in logs

Game crashes on startup

Check TMLoader profile is correctly configured
Verify TMInterface 2.1.0 is installed
Try launching game manually first to verify it works
Check Windows firewall isn’t blocking TMLoader/TMInterface

BC cache: “Sample missing meta/float” or skip_indices

When building BC cache with float inputs (use_full_iqn or use_floats), some frames may lack required metadata (race state snapshots in manifest.json) for the float vector. The cache builder skips such samples and writes skip_indices.json; bad samples are removed from the cache.

Prevention — avoid bad samples at capture time:

# Capture with validation: skip bad frames, replays with no valid frames, and tracks with no replays
python scripts/capture_replays_tmnf.py --replays-dir maps/replays --output-dir maps/img --vcp-dir maps/vcp --skip-bad-float-samples ...

Prevention — clean source data before cache build (if not using –skip-bad-float-samples):

# Scan for bad samples (no output = none found)
python scripts/cleanup_source_metadata.py --data-dir maps/img

# Remove bad samples and empty dirs
python scripts/cleanup_source_metadata.py --data-dir maps/img --apply --yes

Run this before pretrain_bc.py to avoid skip_indices during cache build.

If cache was already built and skip_indices exist — fix cache and optionally clean source:

# Fix .npy files (remove skip rows) and clean source
python scripts/cleanup_skip_indices.py --cache-dir cache/v1 --fix-npy --clean-source --yes

This repairs the cache and removes bad frames from maps/img. After --clean-source, the script updates source_signature in cache_meta.json so the cache stays valid and is not rebuilt.

Scripts:

cleanup_source_metadata.py — validates metadata in source replays before cache build; removes bad frames, empty replays, empty tracks.
cleanup_skip_indices.py — after cache build: fixes .npy files using skip_indices.json, optionally cleans source data.

Linux-specific:

Linux installation checklist: This list is not exhaustive. It contains the main setup steps the authors use on their machine. It may need to be adapted for your own machine.

Update winehq-staging
Download Steam. Install TMNF from Steam
Check that the game can be launched with wine TmForever.exe from the installation directory
Download the ModLoader zip file, made available on Tomashu’s website for linux setups
wine TMLoader.exe to configure the default profile
Check that the game runs with: wine ~/path/to/TMLoader-win32/TMLoader.exe run TmForever “default” /configstring=”set custom_port 8483”
Modify launch_game_pb.sh in the repository with the path to ModLoader on your system
Install winetricks. Apply winetricks dxvk for performance.

Missing OpenAL32.dll

Install OpenAL with wine.