Mod Doctor

Which mod is breaking my game? Mod Doctor answers that, in game, in plain words.

Big modpacks fail in confusing ways: a stack trace that only mentions InventoryGrid.UpdateGui, an error repeated 30,000 times, a patch that silently failed at startup, a friend who joins with an older version of one mod. Mod Doctor watches the game's errors, works out which mod caused each one, explains what it means and what to do, and keeps an eye on your mods and your server.

Versão em português abaixo.

Quick start

1. Install it with your mod manager.
2. Play. If a mod starts causing errors, a notice tells you which one.
3. Press F7 for the full report.

Server owners: install it on the dedicated server too, to compare players' mods with the server's and see every player's problems from the Server tab.

What it does

Diagnose

• Traces every error to a mod, from its stack trace.
• Finds culprits hidden inside game methods. When an error surfaces in a patched vanilla method (DMD<InventoryGrid::UpdateGui>, no mod in sight), it asks Harmony which mods patched that method. If one of them also failed to load part of itself, it is named as the likely culprit.
• Catches startup failures, including those of mods that loaded before Mod Doctor (recovered from the start of LogOutput.log).
• Explains each problem: patch failed to apply, incompatible with this game version, error repeating every frame, error in Valheim's own code, or harmless engine message.
• Flags updates on Thunderstore, highlighting the ones for mods that are causing problems.

Keep the log readable

• After 20 identical copies of an error, repeats are no longer written to LogOutput.log; a one-line "suppressed N more copies" summary is written every minute instead.

Compare with the server

• When you join, the server compares your installed mods with its own: missing, different version, or only yours (normal for client-side mods such as UI, camera or clock).
• Also warns about a mod installed twice (e.g. a manual copy next to the mod manager's copy).

Measure

• FPS, 1% low FPS, worst frame, memory and garbage collections.
• World objects around you, grouped by type: thousands of one building piece or dropped items are the usual cause of lag in big bases.
• The slowest mods to load.
• Mod Doctor's own cost, so you do not have to take its lightness on faith. In our testing it stays around 0.01 ms per frame; performance numbers are only sampled while the window is open.

Server overview (admins)

• Server health (uptime, FPS, memory, objects, players online) and, for every player, their mod differences and their problems, in game. Also written to BepInEx/ModDoctor/summary.txt.

The window (F7)

The window uses Valheim's own fonts and follows the game's language (English or Portuguese).

Examples

A problem, as written to report.txt:

== TeleportEverything 2.9.1  (OdinPlus-TeleportEverything) ==
  - Incompatible with this game version (443x, ~85/s)
    BadImageFormatException: Expected reference type but got type kind 17
    Where: InventoryGrid.UpdateGui
    Mods patching this method: TeleportEverything 2.9.1, Equipment and Quick Slots 3.1.3
    Pinned on this mod because it is the only one of them that also failed to load part of itself.
    The mod expects game code that no longer exists (built for an older Valheim). Update it; if
    there is no update, remove it.
  - Patch failed to apply (1x)
    ArgumentException: Undefined target method for patch method ... GetTooltip_Patch::Postfix(...)
    Where: TeleportEverything.Plugin.Awake

A player's mods compared with the server's, from the server's summary.txt:

##### Your mods vs the server's #####
== Mepzer (2026-09-29 15:16) ==
   version Stonaar-ValheimBuildCamera: 1.10.0 / server 1.9.0

Files

Configuration (BepInEx/config/bub.moddoctor.cfg)

The Server tab is shown to players listed in the server's adminlist.txt; the server checks it again before sending anything.

FAQ

Does it fix errors? No. It tells you which mod causes them, why, and what to do (update, remove, or report to the author).

Does everyone need it? No. It works on its own on a single client. On a server, players without it are unaffected and are never blocked from joining; they just do not show up in the comparison.

Does it slow the game down? See the Performance tab: Mod Doctor measures itself. Most of the time it does nothing; heavier measurements only run while the window is open.

Server and players on different Mod Doctor versions? Everything degrades gracefully: problem reports work with any version; the mod comparison and the Server tab need 1.1 or newer on both sides.

Privacy

• Update check: requests thunderstore.io/api/experimental/package/<package>/ for each installed package. Nothing about you is sent. Disable with Updates.CheckThunderstore = false.
• Server reports: your character name, the list of mod folders you have installed with their versions, and for each problem the mod's name, version, package, error message and where it happened. Sent only to the server you are connected to, and only if it runs Mod Doctor. Disable with Server.SendReportsToServer = false.
• Nothing else leaves your machine.

Limitations

• Errors a mod catches and hides itself are invisible to everyone, Mod Doctor included.
• When several mods patch the failing method and none of them failed elsewhere, all of them are listed as suspects rather than one culprit.
• Load times are only measured for mods that load after Mod Doctor.
• Suppressing repeats keeps LogOutput.log readable; Unity's own Player.log is not affected.

Notes

Written with the help of an AI assistant (Claude) and tested on Valheim 1.0.16 with a 35-mod pack, on Windows clients and a Linux dedicated server.

Mod Doctor (português)

Qual mod está quebrando meu jogo? O Mod Doctor responde isso, dentro do jogo, em linguagem simples.

Como começar

1. Instale pelo seu gerenciador de mods.
2. Jogue. Se algum mod começar a dar erro, um aviso diz qual.
3. Aperte F7 para o relatório completo.

Dono de servidor: instale também no servidor dedicado para comparar os mods dos jogadores com os do servidor e ver os problemas de todo mundo na aba Servidor.

O que ele faz

• Diagnostica: descobre o mod por trás de cada erro, inclusive quando o erro aparece dentro de um método do Valheim alterado por mods (pergunta ao Harmony quem alterou). Recupera falhas da inicialização, explica cada problema e avisa sobre atualizações no Thunderstore.
• Mantém o log legível: depois de 20 cópias idênticas de um erro, grava só um resumo por minuto.
• Compara com o servidor: ao entrar, mostra o que falta no seu jogo, o que está em versão diferente e o que só você tem (normal para mods de cliente). Avisa também sobre mod instalado duas vezes.
• Mede: FPS, 1% mais baixo, pior frame, memória, coletas de lixo, objetos do mundo ao seu redor por tipo (a causa comum de lag em base grande), os mods que mais demoram para carregar e o custo do próprio Mod Doctor (cerca de 0,01 ms por frame nos nossos testes).
• Visão do servidor (admins): saúde do servidor e, para cada jogador, as diferenças de mods e os erros, na aba Servidor e no BepInEx/ModDoctor/summary.txt.

A janela usa as fontes do próprio Valheim e segue o idioma do jogo. Para forçar português, use General.Language = Portuguese em BepInEx/config/bub.moddoctor.cfg.

Perguntas comuns: ele não corrige erros, só diz qual mod causa e o que fazer. Ninguém é obrigado a ter: quem não tem entra no servidor normalmente, só não aparece na comparação. A aba Servidor aparece para quem está no adminlist.txt do servidor.

Privacidade: a verificação de atualizações só consulta a API pública do Thunderstore. O relatório enviado ao servidor contém o nome do personagem, a lista de mods instalados com as versões e os erros de mods (nome, versão, mensagem), e só vai para o servidor em que você está, se ele tiver o Mod Doctor. As duas coisas podem ser desligadas na config.

Changelog

1.1.0

• Redesigned report window in Valheim's own fonts and colours: cards per mod with severity colour, badges, number tiles and bars.
• The report window (F7) now has tabs: Problems, Mods, Performance and, for server admins, Server.
• Mods tab: compares your mods with the server's when you join (missing, different version, only yours) and shows a notice if they differ. Also lists mods installed twice and the slowest mods to load.
• Performance tab: FPS (average and 1% low), worst frame, memory, garbage collections per minute, the world objects loaded around you grouped by type, and Mod Doctor's own cost.
• Server tab (admins): server health, and for every player their mod differences and problems.
• Server summary.txt now includes each player's mod differences.
• New server option Server.ServerOnlyMods: mods players do not need, never reported as missing.
• The report file is only rewritten when something changed.

1.0.1

• Opaque, colour-coded report window (the default IMGUI skin was hard to read over the game).
• Notices only appear while you are in a world; entering a world summarises mods already causing errors, and a mod is announced again when its problem gets worse. Occasional errors stay in the report without a notice.

1.0.0

• First release: error attribution (stack traces and Harmony patch owners), startup failure recovery, classification and advice, log spam suppression, Thunderstore update check, in-game report (F7), and player report collection on dedicated servers.