pardeike/Harmony · error · ArgumentException

cannot be null or empty

Error message

{nameof(id)} cannot be null or empty

What it means

Guard clause validating the identifier passed to the Harmony constructor: a null or empty string was supplied as 'id'. Harmony requires a non-empty unique identifier per instance to scope patch registration and unregistration; without one, instances cannot be distinguished, so construction is aborted. This is a generic validation guard; the input at fault is the constructor argument 'id'.

Solutions

1. Pass a stable, non-empty unique id such as your mod's assembly name or a GUID
2. If the id comes from config, validate it before constructing Harmony and fail with a clear message
3. Use nameof(YourMod) or Guid.NewGuid().ToString() as a guaranteed non-empty source

Example fix

// before
var id = modConfig.PatchId;
var harmony = new Harmony(id);
// after
if (string.IsNullOrEmpty(modConfig.PatchId)) throw new InvalidOperationException("PatchId missing in mod config");
var harmony = new Harmony(modConfig.PatchId);

if (string.IsNullOrEmpty(id)) throw new InvalidOperationException("Harmony id must be a non-empty unique string");
var harmony = new Harmony(id);

bool IsValidHarmonyId([NotNullWhen(true)] string? id) => !string.IsNullOrEmpty(id);

try { harmony = new Harmony(id); } catch (ArgumentException ex) { log.Error("Harmony id missing/empty", ex); return; }

When it happens

Trigger: new Harmony(null), new Harmony(""), or a configuration variable/env var supplying the id that resolves to null/empty at runtime.

Common situations: Mod frameworks reading the patch id from config or metadata files where the field is missing; tests constructing Harmony with a placeholder id that defaulted to empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Ambiguous match for HarmonyMethod
• VariableState: variable of type
• VariableState: variable named
• argumentVariations contains more elements than argumentTypes
• No method found for type=

AI-assisted analysis of pardeike/Harmony@e7872dc170 (2026-09-15). Data as JSON: /api/errors/38138e25a7e0e6f2. Report an issue: GitHub.

Appendix: source

Thrown at Harmony/Public/Harmony.cs:29

	///
	public class Harmony
	{
		/// <summary>The unique identifier</summary>
		///
		public string Id { get; private set; }

		/// <summary>Set to true before instantiating Harmony to debug Harmony or use an environment variable to set HARMONY_DEBUG to '1' like this: cmd /C "set HARMONY_DEBUG=1 &amp;&amp; game.exe"</summary>
		/// <remarks>This is for full debugging. To debug only specific patches, use the <see cref="HarmonyDebug"/> attribute</remarks>
		///
		public static bool DEBUG;

		/// <summary>Creates a new Harmony instance</summary>
		/// <param name="id">A unique identifier (you choose your own)</param>
		/// <returns>A Harmony instance</returns>
		///
		public Harmony(string id)
		{
			if (string.IsNullOrEmpty(id)) throw new ArgumentException($"{nameof(id)} cannot be null or empty");

			try
			{
				var envDebug = Environment.GetEnvironmentVariable("HARMONY_DEBUG");
				if (envDebug is not null && envDebug.Length > 0)
				{
					envDebug = envDebug.Trim();
					DEBUG = envDebug == "1" || bool.Parse(envDebug);
				}
			}
			catch
			{
			}

			if (DEBUG)
			{
				var assembly = typeof(Harmony).Assembly;
				var version = assembly.GetName().Version;

View on GitHub (pinned to e7872dc170)