Common Crash Causes

From Custom Mario Kart
Jump to navigation Jump to search

Sometimes when testing a custom track, the game will fail at times to render the track, causing the console to freeze, usually at a black screen. Here is a list of common problems that can cause Mario Kart Wii to crash. Most of these issues can be checked using Wiimm's SZS Tools.

Initial Loading

If your track doesn't load at all, here are some common causes:

How to Fix Custom Track Black Screen

Required Files

A custom track requires these files to run:

  • course.kmp
  • course.kcl
  • course_model.brres
  • map_model.brres
  • vrcorn_model.brres (unnecessary if you are playing on Dolphin, but required on a real Wii)
  • Any object files for objects used in course.kmp


  • Make sure your MDL0 is version 11.
  • Your MDL0 must be named "course".
  • Before replacing a material with BrawlBox, you should remove all its texture references (unnecessary if you are playing on Dolphin, but required on a real Wii).
  • Your materials must be listed by increasing shader index.
    • In BrawlBox / BrawlCrate, materials with "Shader 0" should be listed first, then materials with "Shader 1", and so on.


  • First thing to try is to remove objects from your KMP that you won't need for your track.
    • Some of them require specific track slots, files, or KCL settings. If you don't need them, get rid of them.

  • Your KMP has an object listed that does not exist in your SZS.
    • Copy the missing files from another track that has them, more likely an official track. Some objects require more than just .brres file(s)!

  • You used an object that requires a route, but one wasn't defined for it OR a route was defined that doesn't exist.
    • Check your KMP for any objects that require routes and add a route for them. If a route exists, set it in the object's settings. If not, create a new route for it, then set it in the object's settings.

  • You have too many objects.
    • Try to reduce the number of objects to be below 200 or place your track on the "SNES Ghost Valley 2" slot - that slot supports more objects.

  • An object has invalid settings.
    • This doesn't always cause a crash but it certainly can contribute. Look at settings from other tracks for these objects if you are not sure how to set them.

  • An object has an invalid ID.
    • You have told the game to load something that isn't even a real object. Either remove this object, set its ID to 00, or change it to something else.

  • You have an object that requires solid ground in an area where there is no solidity.
    • Objects like Thwomps require solid ground beneath them. Move them onto the track or remove them from your KMP.

  • You have two STGI entries.
    • Remove one, as it will both save on space and may stop any conflicts that occur by having course settings set twice.

  • A route with two or less points has smooth/curved setting enabled.
    • Smooth setting only works with routes which have 3 or more points. It must be disabled otherwise.

  • Lap-counting checkpoints.
    • Sometimes, having two or three lap-counting checkpoints with a regular checkpoint in between on the track can cause the game to crash. The game can also freeze if there is one lap-counting checkpoints on either end of the track (only applies to one lap tracks that start and end in separate sections). to either try and fix that, try adding three lap-counting checkpoints at the end or remove the lap-counting checkpoint at the start and leave only one lap-counting checkpoint at the end (if it's a one lap track that ends in a respawn or a cannon), or reduce it to a one lap-counting checkpoint if it's only a track that has the start and finish in the same position.


Check for:

  • Proper KCL flags
  • Two-sided faces
  • Model complexity
  • Collision is properly generated


  • You have a BRRES for an object but it still doesn't load.
    • Make sure the brres isn't corrupted or modified. Also be sure you have anything else required by the object, like effects.
      • Also be sure any custom content inside the BRRES is the correct version.

  • Your file size is very big.
    • Remove files that aren't used by the track.

  • Your map model is missing required bones.
    • Your map_model requires bones named "posLD" and "posRU" to position the map. Without them, the game can crash.

  • Your track doesn't load if replacing certain original tracks.

  • Something else may cause the crash.
    • Remove other custom content (characters, Common.szs, etc) and try again.


These are usually a combination of problems.

  • Game crashes when trying to enter a cannon
    • Be sure your cannon trigger in your KCL matches the cannon ID in your KMP.

  • Game crashes/lags shortly after starting, with flashing colors/geometry
    • This usually happens with a corrupt BRRES, likely a corrupt CHR0 animation. Try replacing the BRRES.

  • Game crashes touching a certain object / part of the track
    • This could be a lot of things, ranging from bad KCL, to missing files, to bad KMP, depending on the situation.

  • Game crashes when watching intro cameras in VS/Grand Prix
    • Your CAME is setup improperly. One of your values are set to something that's impossible
    • Your "Next Camera" is set to a camera that doesn't exist

  • Game works in Time Trials but not in VS/Grand Prix
    • Your "First Camera" is probably wrong.
    • You have a corrupt object that is only set to appear in VS. Check your KMP.

  • Game crashes when a player or computer driver gets an item from an item box with special settings.
    • The reason for this crash is hard to detect because you don't know the get-time for the computer players.
    • The game can also freeze when loading, for the same reason.
    • Remove the special settings of all item boxes for human and computer players (2 different settings).