Add-on ped invisible or crashing? Fix it
An add-on ped that loads as nothing, as a grey or purple mannequin, or that crashes the client almost always comes down to one of six things. Check them in this order.
1. The files are not in stream/
FiveM only streams assets inside a folder named stream (any depth below it). A ped placed in the resource root, or in a folder named models, never loads. Check that every .ydd, .yft, .ytd and .ymt of the ped sits under stream/.
2. peds.meta is missing or not loaded
A new ped needs an entry in peds.meta and the manifest has to load it:
files { 'peds.meta' }
data_file 'PED_METADATA_FILE' 'peds.meta'Without it the model name exists but the game has no ped definition and spawns nothing, or falls back to a default.
3. The names do not match
The model name in peds.meta, the .yft, the .ydd and the .ytd must all use the same base name. One typo and the textures or the drawables silently fail. Lowercase everything; avoid spaces and dashes.
4. Textures too big
A texture dictionary that is too large (a single .ytd over 16 MB, or a handful of 4K maps) may simply not load, which shows as an invisible or untextured ped, and on weaker clients as a crash. Resize the textures; a ped rarely needs more than 2048 px maps.
5. A skeleton GTA does not know
If the ped appears but T-poses, slides or has twisted limbs, its skeleton and weights do not match what GTA’s animations expect. Building on the freemode skeleton avoids this entirely: every animation and emote plays on it.
6. Too many clothing collections
If adding the ped coincides with every male or female MP ped crashing, the issue is not the ped but the clothing collections loaded with it: GTA only loads a limited number of .ymt clothing files per gender. See the YMT limit guide.
Test it in isolation
Start a server with only your framework and the ped, then spawn it with SetPlayerModel. If it works there, another resource is overwriting the same model name or exceeding a limit.
Frequently asked
The ped is invisible but I can see its shadow or name tag. Why?
The model streamed but its drawables did not: usually a texture dictionary that failed to load (too large or wrong name) or drawables named differently from what the model expects.
The ped T-poses and does not animate. Why?
Its skeleton is not one GTA's animations know. Animations play on named bones; a ped built on its own skeleton only plays animations made for it.
Can one broken ped crash everyone?
Yes. A ped whose files exceed streaming limits or whose meta is malformed can crash every client that streams it in, which is why it often looks like a random crash near one location.
Try it free
Create a free account, join the Discord for your credits, and build your first asset in minutes.