ValheimWorldConvertDiag

ValheimWorldConvertDiag

Diagnostic BepInEx plugin for tracking down legacy inventory data that causes Valheim 1.0 world conversion to crash.

This was created after a previously healthy vanilla world failed to load after updating to Valheim 1.0 with:

System.NullReferenceException: Object reference not set to an instance of an object

at ItemDrop+ItemData.IsSameType
at Inventory.AddItem
at Inventory.AddTempItem
at Inventory.LoadOld
at ZDOMan.ConvertInventories

World load failed mid-file. Exiting without save. Check backups!

The same world loaded correctly on the previous Valheim version, including backups going back about a year.

The problem turned out to be one malformed legacy container inventory.

What this plugin does

ValheimWorldConvertDiag patches the legacy world inventory conversion process and logs the inventory and ZDO being processed when conversion fails.

It records details such as:

• inventory size
• loaded item count
• last item name
• prefab hash
• stack size
• durability
• inventory grid position
• crafter data
• ItemData.IsSameType() state
• m_shared null state
• recent items processed in the same inventory
• source ZDO UID
• source ZDO world position
• source prefab hash

The most useful part is the ZDO position.

Instead of manually opening hundreds of chests, you can use the logged coordinates to find the exact world object causing the conversion failure.

Important

This plugin is diagnostic only.

It does not:

• modify world data
• delete items
• skip broken inventories
• suppress the original exception
• automatically repair the world

Always work from a backup.

Confirmed real-world case

The world used to develop this plugin contained more than 1.4 million ZDOs and had never been modded.

Valheim 1.0 failed while converting this legacy inventory:

Inventory size: 4x4
Loaded items before failure: 6

Recent items included:

Wood x50        pos 1,0
Stone x7        pos 3,0
Stone x50       pos 0,1
CharredBone x50 pos 2,1
CharredBone x50 pos 4,1
CharredBone x14 pos 1,1
Wood x38        pos 4,1

The suspicious part was that a 4-wide inventory contained items at:

pos=4,1

and multiple items appeared to overlap at that same position.

The crash occurred inside:

ItemDrop+ItemData.IsSameType

while both ItemData objects had:

m_shared=<null>

The plugin identified the source ZDO as:

UID: 1:183157
Position: (-866.75, 31.46, -8632.98)
Prefab hash: 328745978

That location turned out to be an unimportant chest at an old Ashlands landing camp.

The world was loaded using the previous Valheim version, the offending chests were destroyed, dropped items were removed, and the world was saved again.

After that, Valheim 1.0 converted the world successfully.

Recommended recovery workflow

Do not try to repair the world directly in Valheim 1.0.

The safest process is:

1. Keep an untouched backup of the original pre-1.0 world.
2. Run Valheim 1.0 with this diagnostic plugin.
3. Let conversion fail normally.
4. Read the logged ZDO coordinates.
5. Switch back to the previous Valheim build.
6. Load the same world on that older version.
7. Travel to the logged coordinates.
8. Remove or empty the offending container/object.
9. Save the world normally.
10. Switch back to Valheim 1.0.
11. Try conversion again.
12. Repeat if another malformed inventory is found.

This avoids editing the save file directly.

Using the previous Valheim build

Valheim keeps an older stable branch available through Steam.

For the regular game client:

1. Open Steam.
2. Right-click Valheim.
3. Select Properties.
4. Open the Betas tab.
5. Select the previous stable branch, commonly named:

default_old

1. Let Steam download the older build.
2. Start Valheim.
3. Load the affected world.
4. Fix the object at the coordinates reported by the plugin.
5. Save and exit cleanly.

When finished:

1. Return to Properties > Betas.
2. Switch back to the normal/default branch.
3. Let Steam update to Valheim 1.0 again.
4. Retry the world conversion.

Branch names can change over time, so if default_old is no longer present, use whichever Steam beta branch Iron Gate provides for the previous stable build.

Dedicated server rollback

For a dedicated server, the exact process depends on how the server is installed.

If using SteamCMD, install or update the server using the previous stable branch before loading the world.

Example pattern:

app_update 896660 -beta default_old validate

Do not blindly run this against your production server without backing up the server files and world first.

If using Docker, check how your image exposes Steam beta branches. Many Valheim Docker images allow a Steam branch or beta environment variable.

The important part is that the world must be loaded using a Valheim build from before the failing 1.0 conversion code.

Do not mix converted and unconverted saves

Once Valheim 1.0 successfully converts a world, keep that converted copy separate from the old-format version.

Recommended backup layout:

MyWorld-pre-1.0/
MyWorld-fixed-old-build/
MyWorld-converted-1.0/

Do not repeatedly move the same working copy back and forth between old and new versions.

Use copies.

Dedicated server use

This was developed and tested on a dedicated Valheim server running BepInEx.

Typical plugin location:

/config/bepinex/plugins/ValheimWorldConvertDiag.dll

or, depending on your setup:

BepInEx/plugins/ValheimWorldConvertDiag.dll

The diagnostic log is written to the BepInEx config directory.

On the Docker setup used during development:

/config/bepinex/ValheimWorldConvertDiag.log