GoldSrc Model Troubleshooting List

Jump to Animation Errors
Jump to Texture & UV Errors
Jump to Mesh Errors
Jump to Skinning & Skeleton Errors
Jump to Other Errors and Shutdowns

General QC errors

************ ERROR ************
.\/mesh.smd doesn't exist

Several reasons for this: A spelling error, a wrong $cd directory set, or a specified directory that does not exist on your computer

Cannot find sequence "X"

Can be a number of things, either you have your SMD's in a different directory than the declared $cd directory, a spelling mistake, improperly closed brackets, or missing quotations on another line.

Studiomdl.exe stops responding and/or crashes

This one is pretty hard to diagnose, but most common is your SMD file has a "//" comment in it or something invalid. Some decompiles with "info" or other comments can also cause this. Other times its using a Source Engine formatted SMD.
2nd case:
Using an invalid disk drive letter in an absolute path or directory that does not exist
3rd case:
Using an action tag without a number
4th case:
You didn't put a space between the brackets in a skin change for example spacing has to look like this:
{ "Base_M_D.bmp" }
Where this is wrong: {"Base_M_D.bmp"}
5th case:
A corrupted BMP can also stop the compiler without errors or in crowbar you get:
ERROR: The compiler did not return any status messages.
CAUSE: The compiler is not the correct one for the selected game.

This is a rare case that can happen with certain old alpha/beta/sdk monster bmps that use strange sizes that may not decompile well. You can verify this by checking your BMP thumbnails and if they are not there or the image opens corrupt it could be it. To properly obtain bmps without corrupt decompile in this case you can use HLMV standalones "export all textures".

bogus bone index

SMD formatting problem. This is due to an export issue or a source engine SMD.

Unknown for bbox "bonename"

This happens when you are using $hitbox and the bone its trying to make it on is either a different name, wrong name or was stripped out by the compiler. The compiler will strip out bones that have no verticies attached to it, the only exception is if a child bone of said bone that is parented to it has verticies skinned to it. An example is say you have an arm set of bones an upper, lower and hand. The upper and lower have no verticies attached to it but the hand does. The model will be able to assign hitboxes to the arm bones since the hand is parented and has skinned verticies. If you are using Sven Studiomdl you can use the QC command $keepbone *bonename* to prevent this or $keepallbones.

Unknown Attachment link "X"

Same thing as the hitbox issue only for attachment.

Line "X" is incomplete:

This can be difficult to diagnose since it can be a line way further down in your QC code that is causing the issue, for example having an FPS but with no number on a sequence can cause this or an improperly set brackets {} can do this

Sanity Check: Can not find QC file!:

This is a windows directory issue that can happen with directories with brackets ( ) in the name or spaces and can also happen in Windows10. Best solution is to use Crowbar Tool as your GUI wrapper for studiomdl.exe. Also the older GUIstudiomdl suffers from issues like this so switch to crowbar

Animation Errors

Illegal parent bone replacement in sequence "X" , "X" has "X" reference has "X":

SMD reference skeleton bones mismatch sequence animation bones. Correct in your 3D editor or use $renamebone for a quick fix.
Second case: The bone in question may have been stripped out during compile. The compiler will strip out bones that have no verticies attached to it, the only exception is if a child bone of said bone that is parented to it has verticies skinned to it. An example is say you have an arm set of bones an upper, lower and hand. The upper and lower have no verticies attached to it but the hand does. The model will be able to assign hitboxes to the arm bones since the hand is parented and has skinned verticies. If you are using Sven Studiomdl you can use the QC command $keepbone *bonename* to prevent this or $keepallbones.
Third case: Your root bone may have been changed; this can happen in blender with "Blender Implicit" bone was left checked on export, you can verify by opening the SMD in notepad.

Model looked fine in Blender but animation loading causes bones to flip/compiled model flips bones

This is a current error with BlenderSourceTools where some reference meshes will import with wrong bone rotations and thus when animations are loaded on this skeleton&ref everything breaks. I have a temporary fix for this:

1) import ref mesh, this will look fine but of course is bone flipped
2) in notepad open the ref mesh smd, and copy everything from the start all the way till the end of the skeleton block end (do NOT go into "triangles".)
Paste that into a new document and save as "posefix.smd"
3) back in blender import "posefix.smd". It will now look broken, but go into pose mode, select all then "apply pose as rest pose".

************ ERROR ************
sequence "reload_empty" is greater than 64K

This is a rare error that happens with very complex animations with high nodes & frames. Usually frames past 200~300 range with over 100 bone nodes is likely to put out this error. I cannot pin down the exact combination of nodes to total frames which triggers this but this is my best estimates. 2 solutions:

1: Re-export the animation SMD with a modified FPS 3D model application side which results in lower total exported keyframes in the SMD, then adjust the QC fps to match.
2: Reduce the bone nodes or animation total frames manually

My animation sequence made all the bones of the model shoot off into multiple directions everywhere

Most likley you used a negative value in your $sequence FPS command to attempt to "reverse" your sequence. Don't do that. Second case could be an exporter issue, with a possibility that its confusing other bone objects in your scene.

My NPC model tries to walk but cannot move

This is because walking/running/movement animations using LX need to have the root bone of the model to move in animated space. In most common cases, this can happen when there is an additional bone or leftover from an import that becomes the root bone of the SMD. Most models have "BIP01" as the root, and if there is other unused bones in your animation SMD that may be the root delete it. To verify what bone in your movement animation SMD is, you can open up it in Notepad++ and see the first bone name entries in the header list. Sometimes this problem can be bones like "SMD import" or some meshnames but are unused.

In other cases like a custom NPC that you havent had any root animation; In your 3D editor animate the root bone moving forward using linear motion keys a distance you need per animation cycle. Each unit in your editor is equal to a hammer unit distance travelled.

My model sequence when activated via scripted_sequence plays but then blinks/flashes or jumps when finishing

You likley put a "loop" QC $sequence command in your animated sequence where it doesn't belong. Animations that are to be played and are not looped don't need "loop".

Texture & UV Errors

My models UVs are offset badly from what they used to be

This is a problem that comes with models that were compiled/recompiled with old era Studiomdl.exe which has a UV crunch issue, most commonly the outdated HLSDK and the DoD one. When compiling models use a modern compiler found in the MDL guide here. For models that already have UV damage from many old recompiles, you can do a compensation fix here.

************ ERROR ************
./security_cam.bmp not found

You either don't have the texture in the directory or used a wrong path in your $cdtexture command.
NOTE: If it says ".TGA" or ".TIFF", or ".PSD", then your 3d export was still referencing your working image. You can either change and fix in 3d editor or use Notepad++ to mass replace all incorrect extensions to ".BMP"

************ ERROR ************
texture too large

You used a texture that exceeds 512 pixels on width or length.

BMP X.bmp [-19999998 -19999998] (6260919%) 1025789700 bytes
9999999 -9999999 9999999 -9999999
************ ERROR ************
texture too large

You declared a texture in $texrendermode that exists in your directory but does not exist on the model itself. So either you chose the wrong texture in your QC or your SMD had the wrong one assigned to it.

************ ERROR ************
error -4 reading BMP image ".\/texture.bmp"

BMP image was 24bit color and not 8bit indexed.

A more rare case can happen where you have an image with low colors (4 or less) and a paint program could save as a legacy BMP 1 or 4bit which may display in previews or other viewers as 8 but is not. This is solved by using an alternative index method or making sure your index is using at least more than 4 colors.

************ ERROR ************
error -3000 reading BMP image ".\/texture.bmp"

BMP image saved as an OS/2 format BMP and/or color and not 8bit indexed. This also can happen with GIMP export and can be solved with "Compatiblity Options> Do not write color space information". Its also reccomended to use IRFANVIEW or WALLY to make the 8bit converison

************ ERROR ************
unknown graphics type ".\/default OBJ"

Your material name lacks the .bmp extension.

My skin change does not work

The first skin in the $texturegroup bracket list must be the one that your SMD has on it.
2nd case:
You didn't put a space between the brackets in a skin change for example spacing has to look like this:
{ "Base_M_D.bmp" }
Where this is wrong: {"Base_M_D.bmp"}

My skin change tiles wierdly

Skin changes can only swap between skins of the same resolution; any differences will tile or offset wrong. Solution is to use skins of same resolution.

My CHROME texture looks all one flat color in HLMV, but works in game

This is a Jed's HLMV specific issue with some models that are in a certain position. Currently P2MV also has issues with displaying chrome as well. Use one of the newer Mdl viewers like HLMV:Standalone.

My CHROME texture distorts when I get close to it or viewed at certain angles

As stated in The Chrome Tutorial If you have a model that has everything skinned to a bone in the floor or somewhere offset, this can have some wierd distortion to the chrome since skinned bones are used as the chrome reference point. To fix this add some bones at say center of mass of the model and skin them.

Models textures are all wrong but looked fine in the 3d editor:

Textures were likley tiled across the UV space. Older GoldSrc stuidomdl.exe versions do not support UV tiling. To fix you must take the tiled sections and either overlap in the main UV (1) space or just re-uv the model parts. Newer studiomdl.exe like the Sven-Coop Studiomdl in its SDK CAN tile across UV space

************ ERROR ************
bad command $texrendermode

This means you are using the old HLSDK studiomdl.exe which is very outdated. Switch to one of the new ones I linked at the beginning of the MDL guide.

My masked texture still has blue on it

Either you forgot to set the $texrendermode for the chosen texture to be "masked" or The blue color was not made on the proper index (index 255). To fix index position a step by step is here.

My masked $texrendermode flag didn't activate when verified in MDL editor

Sometimes $texrendermode commands will not work when in a certain order or when lots of other $texrendermodes are present like say additive. Either re-order the $texrendermode (put say the masked one below an additive one lines) or just check the flags in HLMV:Standalone and resave the model.

My masked texture has blue fringe

You resized your image/used a soft edge on your transparent image. You need a hard edge, so use pencil tool or a masked threshold in your paint program.

invalid BMP file/compression

Your BMP texture is not 8bit indexed. Use an image editor to fix this (but be sure to keep a copy of your 24bit version just in case since 8bit conversion is destructive)

Mesh Errors

Model looks good in 3d editor but polygons look faceted:

Your model likley is imported geometry and has explicit normals. If your exporter has the option of exporting in explicit mode use that option.
2nd case:
If you have two bones of the same name on export it can do this to your mesh
3rd case:
In rare cases models with $texrendermode additive can do this when used as separate mesh parts or $bodygroups. Change the order of the meshes in the QC so that anything with chrome or additive is at the bottom most. For example:

$body studio "mainmesh"
$body studio "secondary"
$body studio "fx" //mesh with chrome or additive

too many normals/verticies in model

You went over the per-SMD limit of normals or verticies. Reduce your polycount and/or break up the mesh into different SMDs (also ffs, don't go stupid with your final polycount. Porting high-density badly rigged stuff from gmod will animate horribly and is bad for performance). This can also happen by accident if you ment to export one small part of a model but your exporter did everything in the scene.

Model renders inverted

You have flipped faces so this should be fixed in your 3d editor. Or you can use use "reverse" after your $body line and smd name. This reverses all the triangles in your reference mesh.

Model has holes in it, but looked fine in 3d editor

By default most 3d editors show/render backfaces, where as GoldSrc does not support backface rendering. If you need a reverse side of something you must create it in 3d editor.

Getting wierd dark areas, or inconsistent shadows or smoothing problems

Several reasons: Unwelded vertices, overalpping faces, bad triangulation, overlapping edgeloops, large NGONS (a polygon in your editor with over 4 vertices which results in bad triangulation on export) bad vertex normals, improper use of smoothing groups such as using 1 smoothing across right angles, or errors with imported geometry. This stuff needs to be fixed in your 3d editor.

Skinning & Skeleton Errors

My model is rotated wrong but looked fine in 3d editor:

Most likley is your first or idle sequence has the bone rotated. Either fix in editor or use "rotate" on your problem $sequence line. Second case if you have a separate mesh via $body/$bodygroup it may be having its origin/orientation affected by the 1st mesh or skeleton. Also duplicate names may merge as bone objects. Third case could be model transforms are not committed (apply transforms in blender, and Reset Xform in 3dsmax)

My models limbs crumple/stretch badly when animating

This is a topology issue + hard vertex weight issue. You must modify your topology/edgeloops to compensate for hard vertex weights. There is no vertex weight blending so you cannot spread out a movement over several verts or edgeloops. To compensate remove some loops then create/cut new loops that have further distance on moving parts. Hard-vertex limit favors lower poly/density meshes. Testing movement in your 3D editor and a good understanding of topology and movement is key to fixing this.

My models skinning worked in the editor but is wrong on compile

If you have more than two bones with the same name it can cause issues like this. Also, blender export may have been made with more than two verticies skinned to the same bone. A second issue can easily happen where you have your model properly skinned but accidently set all verticies skinning to 1/RED on one vertex group which overrides all other bones skinning.

Model looks horribly broken with all limbs rotated 90 degrees:

This is a milkshape3D issue where it can break the whole model when you create new bones on a skeleton

Other Errors

Game disconnect with console error:
Server is enforcing file consistency for models/p_usp.mdl
Bad file Server is enforcing file consistency for models/p_usp.mdl

Usually a CS1.6 error due to a violation of certain playermodel P_ weapon model. Most common case is having the mesh of the custom model exceed the hitbox size. Scale down your model to fit within and you should be good.
2nd case:
Making an animation that has the origin move too far

Game Crashes with no error:

If you compiled a multi-MDL model (obsolete QC command sequencegroupsize/externaltextures) and lost one or overwrote one of the parts this may be the culprit. In any case if you have sequencegroupsize/externaltextures in your QC remove them promptly as they cause many issues and are an older obsolete command.
2nd case:
You used a model that was compiled with much greater texture size than 512X512 (Mods like XASH3D support higher limits and do not have this error)

Game Closes with window:

A rare case where a model with an invalid BMP size got compiled. Some custom compilers may cause this for example compiling from the HLSDK which may have incompatible BMP sizes. A solution is either slightly cropping or padding the texture. Valid size dimensions are divisible by 8.