Skip to content

Troubleshooting

Jump to bottom
Electroblob edited this page Jun 23, 2021 · 6 revisions

This page is a how-to for those unfamiliar with fixing mod problems.

This guide is intended for Minecraft 1.12 and Wizardry 4.3, but most of it is relevant to any game/mod version.

Contents

Troubleshooting 101

If you encounter a problem with Wizardry, here's what you should do.

Help me to help you! If you've gone through these steps first, it makes it a lot easier for me to help fix your issue.

1. Check for updates

For Wizardry plus any addons you have installed, check that you're running the latest mod version for the Minecraft version you are playing, and update them if necessary.

2. Check existing issues

Go to the issue tracker and try searching for things related to your issue. For example, if something went wrong when you cast the possession spell, try searching for 'possession' and see what comes up. If you find an existing open issue that matches your problem, then feel free to add a comment with any extra information you might have.

3. Try to reproduce the issue

If an issue can be reliably reproduced, it's a lot easier to investigate. Try to remember what you were doing when the issue happened and see if you can make it happen again by doing any of those things. If you can't reproduce the issue, it is still worth reporting though!

4. Check your config

Many issues can be solved by changing one or two config settings. For example, if you find a mob is not resisting fire magic when it should be, you can add it to the resistances config. Some particularly issue-prone features such as player animations have an option to disable them entirely so you can at least play the game without them.

5. Submit an issue

If you think you've found a bug and none of the above steps fixed it, please report it on the issue tracker. The more information you give me, the more likely I'll be able to fix it!

How to Find Stuff

First, you need to navigate to your game directory. This is the folder that Minecraft runs in, and it contains all of your world saves, mods, resource packs and so on. For vanilla Minecraft, this is the .minecraft folder. Depending on how you set up your modded game, it may be in a different folder.

If you're not sure where it is, an easy way of getting there is to launch your modded game and go to the resource packs menu. Click Open Resource Pack Folder to open up a file explorer window in the resource packs folder, then go up one level. You should see a bunch of folders including saves, mods, and screenshots - this is your game directory.

Crash Reports

Navigate to your game directory and find the folder called crash-reports. Every time Minecraft crashes, it creates a plain text (.txt) file in here. They are named with the date and time they were created so it should be easy to find the most recent one.

Logs

Navigate to your game directory and find the folder called logs. The most important file in this folder is latest.log. If you are asked for a log file, this is probably the one you want. This is the console output for the most recent time the game was run, and it can be opened directly with a text editor. It gets overwritten every time the game is launched so make a copy if you need to keep it!

The rest of the files in the logs folder provide more detailed logs of various parts of the game, including startup, client and server. These can be useful in certain situations, you'll be asked for the relevant one if necessary.

You might also see a bunch of files with dates as their filenames; these are previous log files. Most of them will be .gz files, meaning they are compressed (gzipped). You can open these with an archive program such as 7zip.

Mod List

A good way of getting a mod list is to open the most recent crash report and find the loaded mods table at the end. This is particularly helpful because it gives the version numbers and mod IDs of each mod. If you don't have a suitable crash report, navigate to your game directory, open the mods folder and take a screenshot of everything inside it.

Tips and Tricks

Start afresh

If it's not obvious whether the problem is caused by Wizardry alone or if it's a compatibility issue with other mods, the easiest way to check is to make a fresh installation in a new game directory with just Forge and Wizardry (and any addons, if they are relevant to the problem). Create a new world and then try to reproduce the issue.

If you can't reproduce the issue, it's likely to be a compatibility problem (see below). If not, it's probably a bug with Wizardry itself.

Narrow it down

Think you have a compatibility issue, but not sure which other mod is causing it? Try the following:

  1. Locate the most recent crash report and find the loaded mods table. This gives the mod loading order.
  2. Go to your mods folder and remove all mods in the second half of that list, except for wizardry and any addons that caused the problem.
  3. Launch the game again, create a new world and try to reproduce the issue.
  4. If the issue still happens, repeat from step 2, removing the second half of the remaining mods. If the issue no longer happens, put back the first half of the removed mods and repeat from step 3.
  5. Keep repeating in this way until you have narrowed it down to a single mod.

Doing it by halves is the quickest way to narrow down the list. By always removing mods according to load order, you can be sure you haven't removed a dependency by mistake.

Types of lag

Performance issues are a pain to diagnose! You can help by describing what kind of lag you're experiencing.

  • Server lag is when the server can't update the world quickly enough, and the ticks-per-second (tps) drops below 20. This causes the world to react to player interaction in a delayed manner, for example, if you break a block but you can still stand on it, or if you hit a mob and it doesn't take damage for a while. Server lag affects all connected players similarly.
  • Connection lag is when your connection to the server is slow. This can result in the world freezing and will mean you appear to other players like you are teleporting around rather than moving smoothly. From your perspective this looks very similar to server lag, the key difference is it doesn't affect other players.
  • Client lag is when the client can't update and render the game world fast enough. This is normally very obvious since it results in framerate (fps) drop.

When in singleplayer or hosting a LAN game, server lag can cause client lag (and vice versa) because both are running on the same computer, though this is not always the case.

When it comes to lag, LagGoggles is your friend!

Built-in debug tools

Minecraft has a built-in set of debug tools which can be really useful and are available without having to install extra mods. As well as the familiar debug screen (activated by pressing F3), there are a bunch of other shortcuts that can help with diagnosing problems. Here are a few particularly useful ones:

  • F3 + H toggles advanced item tooltips
  • F3 + B toggles entity hitbox display
  • F3 + G toggles display of chunk boundaries
  • F3 + A reloads all chunks
  • F3 + C deliberately crashes the game when held for 6 seconds (useful for generating an up-to-date loaded mods table and system info)
  • Shift + F3 shows the debug screen with additional profiler pie chart
  • Alt + F3 shows the debug screen with additional frame time (fps) graph

Use F3 + Q to display a list of debug shortcuts in the chat. A full list is also available on Minecraft's help pages.

Querying with commands

You can use vanilla Minecraft commands to quickly show information about specific objects in-game:

  • /entitydata @e[r=2,type=!player] {} will display NBT data in the chat (without modifying it) for all entities standing within 2 blocks of the player
  • /blockdata ~ ~-1 ~ {} will display NBT data in the chat for the block below the player (change the coordinates as necessary)

Crash Report Cheat Sheet

Filename

Crash reports are plain text (.txt) files with names that start with crash- and contain the date and time the crash happened and whether it happened on the client or server side. They are stored in the crash-reports folder inside your game directory.

Example filename:

crash-2021-01-31_20.16.21-client.txt

This crash happened at 8:16 pm on 31st January 2021, and the crash occurred in client-side code.

Header section

Contains a title, randomised splash text, timestamp and general description.

Example:

---- Minecraft Crash Report ----
// Surprise! Haha. Well, this is awkward.

Time: M/DD/YY H:MM AM/PM
Description: Unexpected error

The first two lines are unimportant. The timestamp simply tells you when the crash occurred.

The description gives a very basic overview of what was happening when the error occurred. The main ones are:

  • Ticking entity: The crash happened while updating an entity (basically anything that moves - mobs, xp orbs, etc.) in the game world
  • Ticking player: As above, but for players
  • Ticking block entity: As above, but for tile entities (container blocks - chests, furnaces, etc.)
  • Ticking world or Server tick loop: Something happened while updating the world in general
  • Rendering ___ or Tessellating ___: The crash happened while drawing something in the world or on-screen
  • Updating screen events: Something related to GUIs
  • Saving ___ NBT or Loading ___ NBT: The crash happened while saving or loading a world or chunk
  • Initializing game or There was a severe problem during mod loading...: The crash happened during game startup
  • Unexpected error: Anything else

Stacktrace

The main part of the crash report.

Example:

java.lang.NullPointerException: Unexpected error
	at electroblob.wizardry.util.SpellModifiers.combine(SpellModifiers.java:82)
	at electroblob.wizardry.item.ItemWizardArmour.onSpellCastPreEvent(ItemWizardArmour.java:359)
... etc.

The first line tells you the specific type of error followed by a short description message (often the same as the general description from earlier). Some types usually indicate certain kinds of problem:

  • NoSuchFieldError, NoSuchMethodError and NoClassDefFoundError usually indicate out-of-date mods or addons. On a dedicated server, these can occasionally be caused by mistakes in the code.
  • JSONSyntaxException indicates there is something wrong with the JSON files (usually a missing bracket or comma), i.e. recipes, advancements, spell properties and so on - usually the description message will give more details.
  • OutOfMemoryError indicates that the game has run out of memory (RAM) - contrary to popular belief, allocating more RAM will not fix this issue! It is almost always a mistake in the code. Usually this error is preceded by large amounts of lag - LagGoggles can really help with diagnosing this.
  • StackOverflowError indicates that something has caused an infinite loop, usually two mods triggering each other's event handlers repeatedly. The stacktrace following this error type normally repeats itself many times.

Sometimes you get a second line starting with Caused by:, this indicates the underlying error that caused the first one.

The following list of indented lines mostly starting with at are called the stacktrace. This shows the path through the code (in reverse order) that led to the error. Each of these lines refers to a specific line in the code. For example, the line: at electroblob.wizardry.util.SpellModifiers.combine(SpellModifiers.java:82) refers to the combine method in the SpellModifiers class, which is located in the package (folder) electroblob.wizardry.util. The part in brackets gives the line number within that file, which in this case is line 82.

Walkthrough

Pretty much a repeat of the previous section.

Example:

A detailed walkthrough of the error, its code path and all known details is as follows:
---------------------------------------------------------------------------------------

-- Head --
Thread: Client thread
Stacktrace:
	at electroblob.wizardry.util.SpellModifiers.combine(SpellModifiers.java:82)
	at electroblob.wizardry.item.ItemWizardArmour.onSpellCastPreEvent(ItemWizardArmour.java:359)
... etc.

The only useful line here is the one starting with Thread:. Minecraft runs several processes at once, and this line tells you which one crashed. This indicates whether the crash happened on the client or server side, and will also tell you if it was related to networking.

Level Details

Gives information about the world at the time of the crash.

Example:

-- Affected level --
Details:
	Level name: MpServer
	All players: 1 total; [EntityPlayerSP['Player677'/2068, l='MpServer', x=402.01, y=64.00, z=368.02]]
	Chunk stats: MultiplayerChunkCache: 289, 289
... etc.

There is lots of potentially useful information in here, including the world seed, the number and location of loaded entities, the in-world time and weather, and so on.

System Details

Gives information about your computer and Minecraft setup (don't worry, it's not sensitive info).

Example:

-- System Details --
Details:
	Minecraft Version: 1.12.2
	Operating System: Windows 10 (amd64) version 10.0
	Java Version: 1.8.0_191, Oracle Corporation
... etc.

Again, there is lots of potentially useful information here. Probably the most useful part is the table of loaded mods, which gives the mod ID and version for every mod that was loaded when the crash happened, sorted by load order. It is near the end and looks like the following example:

| State  | ID                  | Version      | Source                           | Signature |
|:------ |:------------------- |:------------ |:-------------------------------- |:--------- |
| LCHIJA | minecraft           | 1.12.2       | minecraft.jar                    | None      |
| LCHIJA | mcp                 | 9.42         | minecraft.jar                    | None      |
| LCHIJA | FML                 | 8.0.99.99    | forgeSrc-1.12.2-14.23.5.2847.jar | None      |
| LCHIJA | forge               | 14.23.5.2847 | forgeSrc-1.12.2-14.23.5.2847.jar | None      |
| LCHIJA | baubles             | 1.5.2        | Baubles-1.12.jar                 | None      |
| LCHIJA | antiqueatlas        | 4.6.3        | antiqueatlas-1.12.2.jar          | None      |
| LCHIJA | jei                 | 4.15.0.291   | jei_1.12.2-4.15.0.291.jar        | None      |
| LCHIJA | ebwizardry          | 4.3.3        | 1.12.2_main                      | None      |
| LCHIJA | antiqueatlasoverlay | 1.2          | antiqueatlas-1.12.2.jar          | None      |

Tools and Resources

LagGoggles

LagGoggles is a mod that shows you what objects in the world are causing lag, and has a bunch of useful profiling tools for narrowing down the problematic code. LagGoggles is available here - simply install it like any other mod and you'll have access to a load of useful troubleshooting tools!

HWYLA

HWYLA is a simple mod that will show you more information about various things in-game when you look at them or hover over them in GUIs. It's available here - again, simply drop it in with the rest of your mods.

Technical Info on Minecraft Wiki

Technical Info on Wizardry's Wiki

  • Commands: Syntax for Wizardry's commands
  • Loot Functions: Structure of Wizardry's loot functions (for use in loot table JSON files)
  • Spell Properties: Explanation and structure of spell properties JSON files

© Electroblob 2021. Details of permissions can be found in the license.

Gameplay

Getting Started
Blocks
Items
Spells
Mobs
Structures
Status Effects
Crafting Recipes

Technical

Commands
Ally Designation System
Minion Targeting
Configuration
Loot Functions
Spell Properties
🎯 Troubleshooting

Development

Changelog
Developing Addons
About and Credits

External Links

⮡  Curseforge Page
⮡  Minecraft Forum Thread
⮡  Feed the Beast Wiki Page
⮡  Legacy Documentation

Clone this wiki locally