Troubleshooting and Compatibility

Troubleshooting and Compatibility

Supported environment

• Target: BeamNG.drive 0.38.6.
• Mode: Free Roam.
• Map requirement: usable road graph.
• Best map results: bus stops, parking/site data, points of interest, and correctly configured gas-station facilities.

TaxiDriverHUD is not available

Check that the archive contains:

ui/modules/apps/TaxiDriverHUD/app.json

directly under the archive root. An extra folder around lua, ui, and mod_info prevents automatic injection.

Also verify that only one TaxiDriver copy is active. Remove either the packed or unpacked duplicate, then reload UI or restart the game.

Start Driving does nothing

The backend refuses startup when:

• there is no active player vehicle;
• the current map has no usable road graph;
• Realistic Mode is enabled but required Free Roam gas-station functions are unavailable.

The phone should show a localized warning. Check beamng.log for entries tagged taxiDriver if the UI does not update.

Dispatcher remains at 0 of 12

Offer generation is intentionally incremental. Large or unusual graphs can take longer than earlier synchronous versions.

If no offer appears after a reasonable period:

1. confirm the vehicle is on or near a public drivable road;
2. test an official map with a known road graph;
3. search the log for Unable to generate taxi offer;
4. check for another mod replacing route, map, or facility functions;
5. remove duplicate TaxiDriver installations.

Multi-stop rides require at least 20 semantic candidates. Their absence is normal on sparse maps and should not block regular rides.

Deliveries require a reachable route of at least 2 km. The dispatcher normally targets 5–7 deliveries but may retain fewer distinct routes on extremely small graphs. Spatial-diversity checks relax after bounded attempts and should not leave the entire pool empty.

Pickup is in an odd location

TaxiDriver projects semantic anchors toward the road edge but depends on map node radius, legal direction, and site placement. Incorrect road widths or distant semantic objects can produce imperfect positions. The fallback prioritizes route validity over perfect curb alignment.

Door does not open

Door animation depends on vehicle trigger names and structure. It is optional. Boarding and alighting continue after the timer even when no supported passenger-side trigger is found.

Cargo loading/unloading uses the same best-effort approach with trunk, tailgate, or cargo-door triggers. The delivery continues normally when the vehicle exposes no compatible trigger.

Boarding screen does not finish

Boarding is controlled by a three-second simulation timer, not by confirmation that the door physically closed. Ensure the game is not paused and that the active vehicle has not changed. A vehicle reset intentionally terminates the shift.

Map appears on the wrong screen

The backend accepts minimap transforms only in navigation phases. If a stale map remains:

1. close/reopen the UI App;
2. leave and re-enter the UI layout;
3. verify there is not a second unpacked TaxiDriver UI script;
4. check for another mod controlling ui_apps_minimap_minimap.

The minimized dashboard owns a separate minimap rectangle. If its map geometry is stale after resizing the UI App, reopen the full phone and minimize it again so the normalized rectangle is recalculated.

UI App text and borders look blurry

BeamNG's UI Maximum Resolution setting can render the complete UI layer below the game-window resolution and then stretch it. This affects TaxiDriver and native BeamNG apps alike; CSS inside an individual UI App cannot opt out of the final upscale.

Open Options → User Interface and set UI Maximum Resolution to None/Disabled for native-resolution rendering. If the interface becomes too small, resize TaxiDriver through the UI Apps editor and use its font-size setting instead of lowering the global UI resolution.

Cargo mass remains after a delivery

TaxiDriver clears cargo mass on completion, cancellation, reset, vehicle switch, mission end, deserialization, and extension unload. If a duplicate packed/unpacked installation runs two GE or Vehicle Lua extensions, cleanup commands can target the wrong instance. Remove the duplicate, reset the vehicle, and reload the session.

Penalties feel too sensitive

Select Elementary or Easy in settings. Difficulty affects speed tolerance, grace period, collision threshold, g-force thresholds, penalty rate, and caps.

Passenger mood also matters. Low-mood passengers can apply a multiplier, while high-mood passengers can ignore eligible episodes.

Passenger demands an early stop

This is triggered by accumulated passenger stress from speeding, collisions, and harsh manoeuvres. It is not a police event. Vehicle input is deliberately overridden until the exit sequence completes.

Refuel button is absent

The orange Refuel action appears only when:

• TaxiDriver is online;
• Realistic Mode was enabled before the shift;
• settings/profile/fuel overlays are not already open.

No compatible fuel station is found

The map must expose gasStation facilities and the active vehicle must report a compatible energy storage. A station's energyTypes may limit compatibility.

Vehicles with custom or unsupported storage types can drive in normal mode but may not use TaxiDriver refueling.

Slider cannot buy fuel

The maximum is limited by both free tank/battery capacity and wallet balance. A nearly full tank or insufficient balance can reduce the range to zero.

The vehicle must remain within the station and at or below 2 km/h.

Refueling is interrupted

The transaction is cancelled before charging the wallet if the vehicle moves, leaves the station, changes, resets, the station context disappears, or the mode goes offline.

Sounds ignore the game volume

TaxiDriver reads BeamNG's Interface Volume, not master or vehicle volume alone, and multiplies it by the TaxiDriver sound-volume setting. Verify Silent Mode is disabled, the required sound-group switch is enabled, and use the adjacent Test button. The Test button skips disabled groups. The UI listens for SettingsChanged, so the effective volume should update without reopening the app.

Cheat Zone rating does not update or causes a Fatal Lua Error

Install version 2.22.2 or newer. Version 2.22.0 could leave the old visible value after pressing Set. The short-lived 2.22.1 callback fix could generate invalid conditional Lua control flow. Version 2.22.2 uses a plain serialized command and republishes authoritative profile/HUD state.

Experimental External Web UI does not open

Connected phone is experimental. It requires:

• free TCP port 8085 on the computer's private IPv4 address;
• inbound private-network permission for BeamNG.drive.x64.exe in the operating-system firewall;
• both devices on the same LAN without guest/client isolation;
• the Connected phone toggle enabled for the current session.

If another process occupies port 8085, TaxiDriver cannot bind its LAN bridge. If BeamNG.drive is denied network access, the bridge can run locally but the phone cannot reach it. A URL working at 127.0.0.1 tests only loopback and does not verify subnet access.

Search beamng.log for taxiDriverLan. Successful startup includes a line similar to:

LAN bridge listening on 192.168.x.x:8085 -> 127.0.0.1:8085

Also check VPN/virtual adapters and router AP isolation. See External Web UI for the complete checklist.

External Web UI connects but Live trip state fails

Install TaxiDriver 2.23.0 or newer. Earlier lightweight external loaders initialized the BeamNG bridge but did not submit the event subscription required for custom GUI hooks. Commands could reach the game while TaxiDriverHUDState was never delivered back to the browser.

After updating, restart BeamNG so it reloads the ZIP, enable Connected Phone again, and reload the page. If the problem remains, search the current beamng.log for taxiDriver, taxiDriverLan, and WebWSServer entries.

External Web UI loads but has no roads

Wait for the detailed loader to finish the live-state and map phases. The complete navigation graph is sent in bounded chunks and cached by the browser. Sparse or custom maps may not expose terrain tiles or a complete road graph. Reload the external page after the level has fully loaded and keep the game running.

Settings reset to defaults

TaxiDriver deliberately recreates a file when JSON is invalid or its schemaVersion is unsupported. Inspect:

current/settings/TaxiDriver/settings.json
current/settings/TaxiDriver/difficulty.json
current/settings/TaxiDriver/profile.json
current/settings/TaxiDriver/progress.json
current/settings/TaxiDriver/lan.json

Restore a compatible backup or allow the file to be recreated.

Invisible walls or tunnel collisions

TaxiDriver does not create collision geometry and does not change tunnel collision meshes. It reads the road graph, controls navigation/UI, and temporarily controls vehicle inputs only during forced passenger exits. Invisible walls are normally caused by the map, vehicle, cached level data, or another mod rather than TaxiDriver route generation.

Mod conflicts

Potential conflict areas include mods that replace:

• freeroam_gasStations.refuelCar;
• freeroam_gasStations.onActivityAcceptGatherData;
• native minimap draw/transform functions;
• ground-marker navigation settings;
• vehicle input events or automatic Vehicle Lua extensions.

TaxiDriver restores borrowed functions conditionally, but wrapper order still matters when multiple mods patch the same global function.

Logs for bug reports

Use the current-version log:

%LOCALAPPDATA%\BeamNG\BeamNG.drive\current\beamng.log

Include:

• game and TaxiDriver version;
• map and vehicle;
• difficulty and Realistic Mode status;
• steps to reproduce;
• relevant taxiDriver log lines;
• whether packed and unpacked copies were present;
• whether Connected phone was active, the LAN URL used (remove its token), and whether TCP port 8085 was free;
• screenshot or short video when the problem is visual.