How to Debug a Rust Oxide Plugin: Compile Errors, Exceptions and Slow Hooks

To debug an Oxide plugin, watch the server console while you save the file, read the first error message, fix it, and reload. Oxide reports three kinds of problems: compile errors (the plugin never loads), runtime exceptions (the plugin loads but a hook, command or timer fails), and performance warnings (a hook runs too long). Each has a distinct log format, covered below. The same workflow applies on Carbon, which loads the same plugin files.

Set up a loop that makes errors visible

Debugging is fastest when you see the result of every edit within seconds.

• Run a local Rust dedicated server with Oxide (or Carbon) installed. See Rust plugin development setup and install Oxide on a Rust server.
• Keep the server console visible in a window next to your editor.
• Save the .cs file into oxide/plugins. Oxide detects the change and reloads the plugin automatically.
• If you want to force it, run oxide.reload PluginName from the console. oxide.load and oxide.unload work the same way. More commands are in Oxide console commands.

After each save, a successful load prints Loaded plugin <Title> v<Version> by <Author>. There is no "compiled successfully" line, so that message is your confirmation. If you do not see it, the plugin did not load; scroll up for an error.

Use oxide.plugins to list what is loaded. A plugin missing from that list failed to compile or failed to initialize.

Reading compile errors

A compile failure looks like this:

Error while compiling PluginName:
[1] The name 'playr' does not exist in the current context at 42:17
[2] ; expected at 57:30

The format is Error while compiling <PluginName>: followed by numbered Roslyn messages, each ending with at <line>:<column>. The line and column refer to your file, counted from 1.

How to work through them:

1. Fix the first error first. One missing brace or semicolon can produce many follow-up messages further down. Fix [1], save, and see what remains.
2. Go to the exact position. Open the file at the given line and column. For a missing semicolon, the reported line is often the one after the actual problem, so check the previous line too.
3. Look at the CS code. The message text is shown in the console, and the CS number is in the compiler log (see next section). Searching the CS code finds the cause quickly.

A failed file is skipped, and the other plugins still compile and load. Nothing else on the server is affected, except plugins that depend on the broken one.

Frequent compile errors

Some errors are not about syntax at all. If Oxide says it cannot find the main class, or the file name does not match, see plugin filename must match main class and unable to find main plugin class. If the Info attribute is the problem, see Info attribute missing.

If a plugin that worked yesterday now fails with does not contain a definition, a Rust update probably changed the game code. See fix Rust plugins after an update.

The oxide/logs folder

The console scrolls quickly, especially on a busy server. Oxide writes its output to files in oxide/logs (Carbon uses carbon/logs). The compiler errors, including the CS code for each message, are recorded there, so open the newest log when the console has already moved on or when you need the exact error code.

Practical habits:

• Open the log file right after a failed reload rather than scrolling the console.
• Search the log for the plugin name to see every error that belongs to it.
• On a live server, check the logs after each wipe-day update before players join.

Runtime exceptions and stack traces

A plugin that compiles can still fail while running. Oxide catches the exception, logs it, and keeps the server alive. The message depends on where it happened:

A stack trace follows. Read it like this:

Failed to call hook 'OnEntityTakeDamage' on plugin 'Example v1.0.0' (NullReferenceException: Object reference not set to an instance of an object)
  at Oxide.Plugins.Example.OnEntityTakeDamage (BaseCombatEntity entity, HitInfo info) [0x00010] in <...>:0

• The text in brackets after the hook name is the exception type and message. This tells you what went wrong.
• The first frame that names your plugin class tells you where. Frames from the game or Oxide below it are the callers.
• The hook name tells you which game event triggered it. Look up its arguments on the hook page, for example OnEntityTakeDamage.

Common exception types have their own pages:

• NullReferenceException in a hook
• InvalidCastException in a hook
• KeyNotFoundException
• Collection was modified during enumeration
• IndexOutOfRangeException in a command
• Failed to run timer
• Failed to initialize plugin

A timer that throws is destroyed, so a repeating task silently stops after its first failure. If a periodic feature "just stops working", look for a timer error earlier in the log. More about timers in Rust plugin timers.

Tracing with Puts and PrintWarning

When the stack trace does not explain the bug, log the values involved. Puts writes a normal line to the console and log; PrintWarning is more visible when you scan output.

private void OnPlayerRespawned(BasePlayer player)
{
    if (player == null) return;
    PrintWarning($"[debug] respawned {player.displayName} at {player.transform.position}");
}

Rules that keep tracing useful:

• Prefix messages with something searchable such as [debug], and remove them when done.
• Print the values you suspect: whether a reference is null, a count, an id, a config value.
• Do not leave logging inside frequently fired hooks such as OnEntityTakeDamage, OnDispenserGather, OnEntitySpawned, OnPlayerInput or OnTick. They fire many times per second and will flood the console and slow the server. If you must trace one, log only when a condition is met, such as a specific player or prefab.
• Use a debug switch in your config so you can turn tracing on without recompiling.

private void Trace(string message)
{
    if (config.Debug) Puts("[debug] " + message);
}

Here config.Debug is a bool in your config class; see Rust plugin config file.

Check that the hook runs at all

If nothing happens, first prove the hook fires. Add one line at the top of the method. If it never prints, the cause is one of these:

• The method name or parameter types do not match the hook signature. Oxide finds methods by hook name and calls only overloads whose parameter types accept the arguments. A parameter declared more specifically than what the game passes (for example BasePlayer where the hook sometimes passes another entity type) makes Oxide skip those calls. See Oxide hooks explained.
• The hook was removed or renamed in a game update. Check monthly hook updates and deprecated hook warnings.
• Another plugin returned a non-null value earlier and cancelled the action. On many hooks any non-null value, true or false, cancels the default behavior, so look for conflicting plugins.
• The plugin is not loaded. Run oxide.plugins.

If the hook runs but the result is wrong, check what you return. For hooks that cancel on any non-null value, return null to keep default behavior. Do not assume true forces the action; check each hook's page.

Common NullReferenceException sources

Most runtime failures are null references. Check these first:

• HitInfo and its members. info, info.InitiatorPlayer, info.Initiator and info.HitEntity can be null, for example with fall or decay damage.
• Players that are not real players. GetOwnerPlayer() on an item returns null for items in a box. NPCs and sleepers can reach hooks that you assumed were players only.
• Connections. player.net or player.net.connection may be null for NPCs or during disconnect.
• Item data. item.info and item.parent can be null on items being created or moved.
• Entities after destruction. A saved or cached entity may be destroyed; check entity == null || entity.IsDestroyed.
• Config and data. A config field missing from an old file, or a data object that was never created, is null until you initialize it.
• Other plugins. A [PluginReference] field is null when that plugin is not loaded. Use Economics?.Call(...). See calling other plugins.
• Unity objects. Components found via GetComponent may be absent.

A defensive pattern:

private object OnEntityTakeDamage(BaseCombatEntity entity, HitInfo info)
{
    if (entity == null || info == null) return null;
    var attacker = info.InitiatorPlayer;
    if (attacker == null || attacker.IsNpc) return null;
    // safe to use attacker and entity here
    return null;
}

Also watch for modifying a list while looping over it, which causes the "collection was modified" exception. Loop over a copy or collect items first, then change them.

Measure slow hooks

Oxide logs a warning when a hook call takes longer than 100 ms:

Calling 'OnEntityTakeDamage' on 'Example v1.0.0' took 134ms

If a garbage collection happened during the call, the message ends with [GARBAGE COLLECT]. That points at heavy allocation rather than slow logic. See took ms hook performance warning and took average ms garbage collect.

To find the cause:

• Look for loops over BaseNetworkable.serverEntities or BasePlayer.activePlayerList inside frequent hooks. Cache results or run them on a timer instead.
• Avoid building strings, lists or lambdas on every call of a hot hook.
• To measure a block yourself, record UnityEngine.Time.realtimeSinceStartup before and after and print the difference only if it exceeds a threshold.

float start = UnityEngine.Time.realtimeSinceStartup;
DoExpensiveWork();
float ms = (UnityEngine.Time.realtimeSinceStartup - start) * 1000f;
if (ms > 20f) PrintWarning($"DoExpensiveWork took {ms:0.0} ms");

More techniques are in Rust plugin performance.

Test with a second account

Many bugs only show up with two players: damage between players, team and clan logic, permissions, loot locks, teleport requests, and anything with "owner" or "other player".

• Join with your main account and a second Steam account or a second game client if you have one. A friend can also join your local server.
• Grant permissions to one account only, so you can compare behavior with and without them: oxide.grant user <name|id> pluginname.use. Check with oxide.show user <name>. See Oxide permissions and groups.
• For admin-only effects, remember that admins can bypass some checks, so test the normal-player path with a non-admin account.
• Test disconnect and reconnect too, using OnPlayerDisconnected and OnPlayerConnected, and test with sleepers present.

Check lifecycle problems

Several bugs come from running code at the wrong time. The order is Init, config and lang loading, Loaded, then OnServerInitialized. On a running server the plugin loads after startup, and OnServerInitialized is called immediately with false. Plugins that touch entities or players in Init can fail on a fresh boot because the world is not ready. Move that work to OnServerInitialized.

Also confirm that Unload cleans up. A leftover timer or UI after oxide.reload makes behavior look doubled. Destroy timers and CUI in Unload. See Rust CUI basics.

Other startup messages worth recognizing: duplicate permission registered, missing plugin name prefix for permission, and failed to load config file. A corrupt config makes the plugin fall back to defaults only if you coded that fallback; see the config guide.

A short debugging checklist

1. Did it load? Look for Loaded plugin, or run oxide.plugins.
2. If not, read Error while compiling and fix error [1] first.
3. If it loaded, trigger the action and watch for Failed to call hook or Failed to run command.
4. Find the first stack frame in your class and check each member on that line for null.
5. Add a temporary trace line to confirm the hook fires and the values are what you expect.
6. Test as a non-admin with and without permission, with a second account.
7. Watch for took ...ms warnings after the fix.

If you want a clean starting point that already contains null checks, config, lang and permission handling, the plugin generator produces one. For writing from scratch, see how to make a Rust plugin.