troubleshooting Can't load a texture overlay (CompositeTexture) on any entity

[Jantek]

I can't get a texture overlay to work on an entity texture.

In vanilla code I saw texture overlays are done on blocks and items, none on entities. On the other hand the official API for CompositeTexture class doesn't state anywhere that it should be limited only to blocks and entities.

A simple reproducible example, let's modify fox-adult.json (not using json patching to make it even simpler). Let's add a winter (arctic) overlay to every fox.

Vanilla json (fox-adult.json):

[...]
client: {
	renderer: "Shape",
	shape: { base: "entity/animal/mammal/fox/fox-{gender}" },
	texture: { base: "entity/animal/mammal/fox/{type}-{gender}" },
[...]

a legacy-themed edit:

[...]
client: {
	renderer: "Shape",
	shape: { base: "entity/animal/mammal/fox/fox-{gender}" },
	texture: {
		base: "entity/animal/mammal/fox/{type}-{gender}",
		overlays: [  "entity/animal/mammal/fox/arctic-{gender}" ]
	},
[...]

a modern BlendedOverlay edit:

[...]
client: {
	renderer: "Shape",
	shape: { base: "entity/animal/mammal/fox/fox-{gender}" },
	texture: {
		base: "entity/animal/mammal/fox/{type}-{gender}",
		blendedoverlays: [ { base: "entity/animal/mammal/fox/arctic-{gender}" } ]
	},
[...]

And that, when loading a world (1.21.6 stable, no other mods), causes this error log:

27.3.2026 20:13:32 [Client Fatal] Caught unhandled exception in EntityTextureCollection thread. Exiting game.
27.3.2026 20:13:32 [Client Error] Exception: The given key 'game:entity/animal/mammal/fox/red-male++0~game:entity/animal/mammal/fox/arctic-male' was not present in the dictionary.
   at System.Collections.Generic.Dictionary`2.get_Item(TKey key)
   at Vintagestory.API.Datastructures.OrderedDictionary`2.get_Item(TKey key) in VintagestoryApi\Datastructures\Dictionary\OrderedDictionary.cs:line 253
   at Vintagestory.Client.NoObf.EntityTextureAtlasManager.CollectTextures(List`1 entityClasses) in VintagestoryLib\Client\Render\Atlas\EntityTextureAtlasManager.cs:line 94
   at Vintagestory.Client.NoObf.ClientSystemStartup.loadAsyncEntityAtlas(List`1 entityClasses) in VintagestoryLib\Client\Systems\Startup.cs:line 559
27.3.2026 20:13:32 [Client Warning] ===============================================================
27.3.2026 20:13:34 [Client Fatal] Game Version: v1.21.6 (Stable)
27.03.2026 20:13:34: Critical error occurred
Loaded Mods: game@1.21.6, toomanyteeth@1.0.0, creative@1.21.6, survival@1.21.6
System.NullReferenceException: Object reference not set to an instance of an object.
   at Vintagestory.GameContent.EntityBehaviorTexturedClothing.GetTextureSource(EnumHandling& handling) in VSEssentials\Entity\Behavior\EntityBehaviorTexturedClothing.cs:line 63
   at Vintagestory.API.Common.Entities.Entity.GetTextureSource() in VintagestoryApi\Common\Entity\Entity.cs:line 1209
   at Vintagestory.GameContent.EntityShapeRenderer.GetTextureSource() in VSEssentials\EntityRenderer\EntityShapeRenderer.cs:line 297
   at Vintagestory.GameContent.EntityPlayerShapeRenderer.TesselateShape() in VSEssentials\EntityRenderer\EntityPlayerShapeRenderer.cs:line 58
   at Vintagestory.GameContent.EntityShapeRenderer.BeforeRender(Single dt) in VSEssentials\EntityRenderer\EntityShapeRenderer.cs:line 350
   at Vintagestory.GameContent.EntityPlayerShapeRenderer.BeforeRender(Single dt) in VSEssentials\EntityRenderer\EntityPlayerShapeRenderer.cs:line 165
   at Vintagestory.Client.NoObf.SystemRenderEntities.OnBeforeRender(Single dt) in VintagestoryLib\Client\Systems\Render\RenderEntities.cs:line 71
   at Vintagestory.API.Client.DummyRenderer.OnRenderFrame(Single deltaTime, EnumRenderStage stage) in VintagestoryApi\Client\API\IClientEventAPI.cs:line 87
   at Vintagestory.Client.NoObf.ClientEventManager.TriggerRenderStage(EnumRenderStage stage, Single dt) in VintagestoryLib\Client\Util\ClientEventManager.cs:line 257
   at Vintagestory.Client.NoObf.ClientMain.TriggerRenderStage(EnumRenderStage stage, Single dt) in VintagestoryLib\Client\ClientMain.cs:line 827
   at Vintagestory.Client.NoObf.ClientMain.MainRenderLoop(Single dt) in VintagestoryLib\Client\ClientMain.cs:line 879
   at Vintagestory.Client.NoObf.ClientMain.MainGameLoop(Single deltaTime) in VintagestoryLib\Client\ClientMain.cs:line 751
   at Vintagestory.Client.GuiScreenRunningGame.RenderToPrimary(Single dt) in VintagestoryLib\Client\MainMenu\Screens\GuiScreenRunningGame.cs:line 172
   at Vintagestory.Client.ScreenManager.Render(Single dt) in VintagestoryLib\Client\ScreenManager.cs:line 719
   at Vintagestory.Client.ScreenManager.OnNewFrame(Single dt) in VintagestoryLib\Client\ScreenManager.cs:line 663
   at Vintagestory.Client.NoObf.ClientPlatformWindows.window_RenderFrame(FrameEventArgs e) in VintagestoryLib\Client\ClientPlatform\GameWindow.cs:line 112
   at OpenTK.Windowing.Desktop.GameWindow.Run()
   at Vintagestory.Client.ClientProgram.Start(ClientProgramArgs args, String[] rawArgs) in VintagestoryLib\Client\ClientProgram.cs:line 347
   at Vintagestory.Client.ClientProgram.<>c__DisplayClass10_0.<.ctor>b__1() in VintagestoryLib\Client\ClientProgram.cs:line 131
   at Vintagestory.ClientNative.CrashReporter.Start(ThreadStart start) in VintagestoryLib\Client\ClientPlatform\ClientNative\CrashReporter.cs:line 104
   at Vintagestory.Client.ClientProgram..ctor(String[] rawArgs) in VintagestoryLib\Client\ClientProgram.cs:line 131
   at Vintagestory.Client.ClientProgram.Main(String[] rawArgs) in VintagestoryLib\Client\ClientProgram.cs:line 51
   at Vintagestory.ClientWindows.Main(String[] args) in VintagestoryClient\Windows\ClientWindows.cs:line 11

So, am I missing something? Please help :v 

Thanks!