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.

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 and use the adjacent Test button. The UI listens for SettingsChanged, so the effective volume should update without reopening the app.

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 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.