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 Shift 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 normally terminates the shift; the Cheat Zone God Mode toggle can preserve it for testing.

Vehicle parts take several seconds to apply

Install 3.0.0 Beta or newer. TaxiDriver telemetry and cargo support are now lazy-loaded, and Vehicle Config suspends the UI root plus vehicle-side scans while BeamNG rebuilds the vehicle VM. After leaving Vehicle Config, TaxiDriver waits 1.5 seconds before restoring telemetry, cargo mass, and energy reads. If the delay remains, enable Debug logging and include [TaxiDriver] area=vehicle records with the report.

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.

Connected Phone Test works but game-event sounds do not play on iPhone

Install TaxiDriver 2.24.0 or newer, then reload Connected Phone and tap once anywhere inside the TaxiDriver page. Safari requires a user interaction before it allows Web Audio to run. Version 2.24.0 uses one unlocked audio context for all seven sound groups and queues eligible events for up to five seconds while that context is suspended or still decoding.

If sound stops after switching applications, return to Safari and tap the page again. Also verify that the iPhone is not in Silent Mode, the browser tab is audible, TaxiDriver Silent Mode is disabled, and the relevant sound-group switch is enabled.

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.

Tank / battery level sends the wrong percentage

Install 3.0.0 Beta or newer. The Set button reads the current HTML range value directly and sends it through the same core_vehicleBridge energy-storage path as Realistic Mode. With Debug logging enabled, verify the selected value in [TaxiDriver] area=operation event=cheatSetEnergyPercent.begin and the storage count in energy_percent_applied.

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.

In 3.0.0 Beta, also verify that External map is enabled. If roads appear but terrain does not, enable Terrain layer or confirm that the map exposes usable minimap tiles.

In-game and Connected Phone screens disagree

Install 3.0.0 Beta or newer. HUD packets now carry an epoch and revision; a missed or delayed patch triggers an automatic full-state request. Restart BeamNG after replacing the ZIP so both the external bootstrap and game runtime use the same cache revision. Include [TaxiDriver] LAN/runtime records if divergence persists.

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/shiftshistory.json
current/settings/TaxiDriver/fleet.json
current/settings/TaxiDriver/lan.json

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

AI reports Route Done before the destination

Install 3.1.0 Beta or newer. TaxiDriver now observes BeamNG's native Route Done immediately, compares the vehicle against the physical trip/fuel target, and starts a low-speed exact approach when the road node ends outside the trigger. With debug logging enabled, look for route_done_before_target, direct_approach_started, and direct_approach_completed under [TaxiDriver] area=autopilot.

AI remains at Watching for clear lane

Traffic stopped at a red/yellow signal should be classified as a signal queue. The supervisor rescans the lead and signal every update and restores normal route/speed control when the lead moves or disappears. In 3.1.0 Beta, waiting_traffic_cleared confirms that release. If it remains stopped, include the preceding adaptive_bypass_waiting reason, current map/intersection and traffic arrangement in the report.

AI does not start the engine or select Reverse

TaxiDriver switches a supported vehicle controller to Arcade once and repeats ignition/starter requests until the combustion powertrain reports ready. Version 3.1.1 RC deliberately leaves Arcade selected after AI is disabled, avoiding repeated mode changes and allowing BeamNG to handle the clutch during reverse recovery. Community vehicles with a custom main controller may not expose the standard methods; include taxiDriverAutopilotRecovery log records and the exact vehicle/configuration.

A fleet driver stops working

Open My Fleet and inspect its status. Waiting for salary means the wallet could not cover the next ten-minute wage; the worker resumes when the wage becomes affordable. Planning route can appear temporarily while the current map graph cannot supply a route in the configured distance range. If the vehicle itself was deleted or replaced by another mod, TaxiDriver removes the stale live employee while retaining completed statistics.

Capturing a detailed AI failure

Enable AI trip debug log in AI Driver settings before taking control. TaxiDriver immediately creates a streaming file in:

%LOCALAPPDATA%\BeamNG\BeamNG.drive\current\taxidriver_ailog_<timestamp>.jsonl

Reproduce the problem, then disable AI manually. Attach that JSONL file together with beamng.log, the map, vehicle/configuration, target type, and the visible traffic arrangement. The AI journal is flushed record by record, so it is still useful after a crash. Leave the switch off during ordinary play when detailed telemetry is not required.

A saved shift disappeared or cannot be restored

shiftshistory.json intentionally retains only shifts with at least one completed ride. After BeamNG's vehicle registry loads, TaxiDriver also deletes history entries whose model/configuration no longer exists. Reinstall the missing vehicle mod before launching TaxiDriver if the configuration should remain selectable. A restore already in progress ignores duplicate clicks until the replacement VM settles.

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 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 lines beginning with [TaxiDriver];
• the matching taxidriver_ailog_<timestamp>.jsonl when the issue concerns AI driving;
• 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.