FiveM add-on vehicle troubleshooting: causes and fixes

Symptom	Most likely cause	Fix
Spawn command says the model does not exist	Resource not started, vehicles.meta not loaded, or modelName differs from the .yft name	Will not spawn
Vehicle is invisible or appears late	Oversized model or textures; missing _hi.yft	Invisible vehicle
White, grey or missing textures	txdName differs from the .ytd name, or a texture is not in the dictionary	Missing textures
Vehicle falls through the ground	Model exported without collision	Falls through the map
Drives like another car, or handling edits do nothing	handlingId does not match, or the name is used twice	Wrong handling
No tuning parts, or parts of another car	Duplicate kit ID in carcols.meta	Tuning problems
Name shows as NULL or a code	No text label for gameName	Wrong name
Player sits wrong or cannot get in	Layout does not fit the model's bones	Seats and entry

Before anything else, look at the server console when the resource starts and at the client console (F8) when you spawn the vehicle. Both name the file they have a problem with.

If the game says the model does not exist, the vehicle was never registered. Check these in order:

1. The resource is running. ensure mycar is in server.cfg and the folder name is spelled the same. A folder inside a category folder such as [cars] is fine.
2. vehicles.meta is in both files and data_file 'VEHICLE_METADATA_FILE', with the right path. See the data_file reference.
3. The names match. The spawn name is modelName, and the model file must be stream/<modelName>.yft.
4. The XML is valid. One unclosed tag makes the whole file unreadable. Open it in an editor that checks XML.
5. The files are extracted. FiveM does not load .rpf archives placed in stream, so the .yft and .ytd files have to be taken out of them.

stream/mycar.yft                 <modelName>mycar</modelName>
stream/mycar.ytd                 <txdName>mycar</txdName>
handling.meta <handlingName>     <handlingId>MYCAR</handlingId>
carvariations.meta <modelName>   <modelName>mycar</modelName>
vehiclelayouts.meta <Name>       <layout>LAYOUT_STANDARD</layout>
carcols.meta <kitName>           carvariations.meta <kits><Item>

If a paid resource does not start at all and the console says "You lack the required entitlement", the cause is the server key, not the vehicle: see how to fix the entitlement error.

A vehicle that spawns (you can sit in it, the camera follows it) but is not drawn is nearly always a streaming problem.

• Oversized files. Check the server console for "uses ... MiB of physical memory". FXServer itself says these "lead to streaming issues (such as models not loading/rendering)". Shrink the textures as described in vehicle model files and the 16 MiB warning.
• Missing _hi.yft. When the first lodDistances value is above zero, the game asks for <modelName>_hi.yft for vehicles close to the camera. Ship that file with exactly that name.
• Too many heavy vehicles in one place. Memory adds up per unique model, so a car meet can fail where a single car works.

• Dictionary name. txdName in vehicles.meta must equal the .ytd file name without the extension.
• Texture not in the dictionary. Open the .ytd and check that every texture the materials use is there under the same name.
• Shared textures. If the model relies on textures from vehshare or from a shared dictionary of a vehicle pack, that dictionary must be the parent of the vehicle's dictionary in txdRelationships.
• Liveries. They need FLAG_HAS_LIVERY and textures ending in _sign_1, _sign_2 and so on.

The collision of a vehicle is stored inside the .yft. A model exported without collision bounds has nothing to rest on, so it drops through the road or sinks to its roof. This has to be fixed in the model: open it in the tool it was made with, add the collision and export again. No meta file can fix it.

If only the wheels sink or the body scrapes the ground, the collision is there and the problem is suspension: see fSuspensionRaise and the travel limits in handling.meta explained.

How to add the bounds in Blender is in how to set up vehicle collision in Sollumz.

• Name mismatch. handlingId in vehicles.meta must equal handlingName in handling.meta.
• File not loaded. handling.meta needs files plus data_file 'HANDLING_FILE'.
• Name used twice. If two resources define the same handlingName, your edits may be going into the one the game is not using. Use a unique name per vehicle.
• Wrong sub-handling block. A VEHICLE_TYPE_BIKE needs CBikeHandlingData, a car CCarHandlingData.
• Edits not applied. Restart the resource, reconnect and spawn a fresh vehicle before judging a change.

Kit IDs in carcols.meta are shared by every vehicle on the server. When two kits have the same id, the game moves one of them to another ID, and vehicles that use that kit can end up with the wrong parts or none. Change the id to a number no other vehicle uses. Siren and light IDs clash in the same way.

Also check that the kit name in the kits list of carvariations.meta equals kitName in carcols.meta, and that every part model named in the kit is in the stream folder. Details in carvariations and carcols explained.

The carcols ID conflict checker lists every kit ID used by more than one carcols.meta on the server.

gameName is a text label key, not the name itself. Add the label in a client script, and keep the key to 11 characters or fewer:

-- client script: readable name for <gameName>MYCAR</gameName>
AddTextEntry('MYCAR', 'My Car GT')

The layout in vehicles.meta decides seats and entry animations, and it expects certain bones in the model: seat bones such as seat_dside_f and door bones such as door_dside_f. Pick a layout made for the same kind of vehicle (a bike layout for a bike, a two-door layout for a two-door car), and check that the model has the bones the layout names. How layouts are built is in vehiclelayouts.meta explained.

If none of this helps, rebuild the resource from scratch with how to add an add-on vehicle to FiveM and test after each file.