> For the complete documentation index, see [llms.txt](https://docs.rainmad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rainmad.com/resources/decal-v-graffiti-and-vehicle-sticker/troubleshooting.md).

# Troubleshooting

Every failure mode surfaces in the debug overlay. Open it with `/decals_debug` (admin-only; `/decals_debug <serverId>` opens it on another player's screen so they can read values to you), then check the cards top to bottom.

### 1. DECALS.DAT PROBE says FAILED

The decal types from `rm_decalv_assets` never registered in this session, so nothing can render no matter what else is right. Two causes:

* **The player joined while `rm_decalv_assets` wasn't running.** Its decal types mount when the game level loads, i.e. at join. Make sure it starts at boot, then have the player **reconnect**. Restarting `rm_decalv_assets` does *not* fix already-connected players.
* **Another resource owns the level meta.** Check the **GTA5.META OWNERS** card: it must say `rm_decalv_assets (expected)`. If a map/meta resource is listed instead, it wins the `replace_level_meta` conflict. Load it before `rm_decalv_assets` or remove its override.

### 2. DECAL TYPE SLOTS shows 31 instead of 280

Milder form of check 1, same causes: the player joined while `rm_decalv_assets` wasn't running, either because it never started at boot or because it was being restarted at that moment. The session then falls back to the game's own 31 built-in decal types, so decals render but only 31 distinct textures fit. Start `rm_decalv_assets` at boot, leave it running, and have the affected player reconnect to restore the full 280.

### 3. CATALOG isn't "Loaded"

The client never received the catalog. Read the **server** console from the last `rm_decalv` start:

* `File not found: [x.webp]` means the entry was pruned; the image is missing from `rm_decalv/assets/`.
* `[x] has an unsupported file extension` means only webp/png/jpg are accepted (gif when enabled).
* A Lua error in `decals.lua` stops the whole catalog. Fix the syntax and restart.

### 4. One specific decal is blank

While placing, a small **preview sprite** sits in the bottom-right corner showing the raw texture. Read it like this:

* **Sprite visible, decal missing:** the texture is fine; the decal types didn't register in this session. Back to checks 1 and 2.
* **Sprite blank too:** the texture never resolved. Wrong `textureDict`/`textureName`, the ytd isn't in `rm_decalv_assets/stream/`, or the dict was updated without players reconnecting. For image-file decals, check the **RUNTIME TEXTURE POOL** card: a full bucket (e.g. `512² 16/16`) means too many distinct image decals are in range at once, so move the pack into a dictionary (recommended method).

### 5. Decals exist but don't draw right now

The **RENDERING** card counts what's loaded vs what's drawn:

* **Graffiti rows > rendered:** the extras are beyond `cfg.rendering.distance` or over `cfg.rendering.graffitiBudget` (farthest drop first).
* **Sticker vehicles tracked > 0, rendered 0:** the vehicles are out of render range, or currently hidden by visibility culling (blocked from view / behind the camera); they redraw as soon as they come back into view.
* **Only one player affected:** ask them to open the catalog and check the gear icon: players can turn sticker and graffiti rendering off for themselves, and the choice persists between sessions.

### 6. Decals vanish near a specific vehicle (ENGINE says Stalled)

The **ENGINE** cell in the status strip probes live whether GTA's decal engine is accepting new decals. If it reads **Stalled**, some vehicle model on your server is overloading the engine: unoptimized high-poly conversions make every decal cost many times more than it should, and past a budget the engine stops creating **any** new decals in that player's game (all decal types, other scripts' decals included) until the load drops. The stall is per client, but every player who renders that vehicle's stickers hits the same wall on their own screen, so in practice it reads as server-wide. Typical symptoms: previews stop rendering near a certain car, stickers on healthy cars blink out and return when that car is stored.

The script protects itself automatically (it sheds load and recovers), but the real fix is finding and blacklisting the model:

1. Add `cfg.dev = true` to `cfg.lua` and restart the resource.
2. Run `/decals_meshprobe <model>` for a suspect, or `/decals_meshprobe all` to sweep every vehicle model on the server (takes a while; `/decals_meshprobe stop` aborts).
3. The run ends with a summary and **ready-to-paste `cfg.blacklistModels` lines** for every model that stalled the engine. Paste them, remove `cfg.dev`, restart.

For the vehicle's creator: the fix on their side is lowering body-panel polygon density, adding real LODs, and making the collision match the visible body. Vanilla-quality models pass the probe with a wide margin.

### 7. Flip switch is greyed out

Expected in three cases: the decal is a GIF (no flip variant exists), the texture dictionary has no `<dict>_f` twin (build one with `ytd-flip`), or you're placing on a wall (graffiti has no flip).

### 8. Console warnings worth acting on

Since 3.3.0 routine self-healing messages sit behind verbose logging so consoles stay quiet; run `setr ox:printlevel:rm_decalv verbose` (before resource start) when you want the full diagnostic stream. The warnings below always print:

* `decal capacity: X of 280 slots...`: see check 2.
* `Asset ... uses N MiB of physical memory`: a custom ytd is oversized; split it into smaller dictionaries.
* `no texture source registered for x.webp`: a placed decal's catalog entry was removed. Delete the orphaned decal from the admin panel or restore the entry.
* `N asset file(s) not referenced by decals.lua`: imported files whose snippet never got pasted. Paste the entries or delete the files.

{% hint style="info" %}
Still stuck? Open a ticket in our [Discord](https://discord.gg/rainmad) with your server console output and a screenshot of the debug overlay. Those two cover nearly every case.
{% endhint %}