{"record":{"id":"9066921999b2c18f","repo":"icsharpcode/ILSpy","slug":"the-handle-must-not-be-nil","errorCode":null,"errorMessage":"The handle must not be nil.","messagePattern":"The handle must not be nil\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"ICSharpCode.Decompiler/Documentation/IdStringProvider.cs","lineNumber":134,"sourceCode":"\t\t\t\t\t\t\t|| !metadata.StringComparer.Equals(metadata.GetPropertyDefinition(sibling).Name, name))\r\n\t\t\t\t\t\t{\r\n\t\t\t\t\t\t\tcontinue;\r\n\t\t\t\t\t\t}\r\n\t\t\t\t\t\tif (GetIdString(module, sibling, cppCliDialect: true) == roslynForm)\r\n\t\t\t\t\t\t\treturn true;\r\n\t\t\t\t\t}\r\n\t\t\t\t\treturn false;\r\n\t\t\t\t}\r\n\r\n\t\t\t\tdefault:\r\n\t\t\t\t\treturn false;\r\n\t\t\t}\r\n\t\t}\r\n\r\n\t\tstatic string GetIdString(MetadataFile module, EntityHandle handle, bool cppCliDialect)\r\n\t\t{\r\n\t\t\tif (handle.IsNil)\r\n\t\t\t\tthrow new ArgumentException(\"The handle must not be nil.\", nameof(handle));\r\n\r\n\t\t\tvar metadata = module.Metadata;\r\n\t\t\tvar b = new StringBuilder();\r\n\r\n\t\t\tswitch (handle.Kind)\r\n\t\t\t{\r\n\t\t\t\tcase HandleKind.TypeDefinition:\r\n\t\t\t\t\tb.Append(\"T:\");\r\n\t\t\t\t\tAppendTypeDefinitionName(b, metadata, (TypeDefinitionHandle)handle);\r\n\t\t\t\t\tbreak;\r\n\r\n\t\t\t\tcase HandleKind.FieldDefinition:\r\n\t\t\t\t\tb.Append(\"F:\");\r\n\t\t\t\t\tAppendFieldIdString(b, metadata, (FieldDefinitionHandle)handle);\r\n\t\t\t\t\tbreak;\r\n\r\n\t\t\t\tcase HandleKind.MethodDefinition:\r\n\t\t\t\t\tb.Append(\"M:\");\r","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/icsharpcode/ILSpy/blob/60c08fcb74fcc183130f73c861ed35cf944d0bf1/ICSharpCode.Decompiler/Documentation/IdStringProvider.cs#L116-L152","documentation":"ArgumentException thrown by the GetIdString(MetadataFile, EntityHandle) worker when the supplied EntityHandle is nil (row id 0). XML doc ID strings describe exactly one concrete metadata entity, and a nil handle encodes 'no entity', so the worker refuses it. The public GetIdString(this IEntity) path already pre-checks entity.MetadataToken.IsNil, so reaching this throw means a caller invoked the handle-based overload directly and bypassed that guard.","triggerScenarios":"Calling GetIdString(module, handle) with a handle obtained from a source that can yield nil: typeDef.GetDeclaringType() on a top-level type, a property/event's declaring-type lookup, or entity.MetadataToken on an entity that is not metadata-backed, without an IsNil guard.","commonSituations":"Iterating every member/type in a table and feeding each handle to GetIdString; resolving the declaring type of properties or events (which can be nil for edge cases); converting a handle that came from a lookup that may not have matched anything.","solutions":["Check handle.IsNil before calling GetIdString and skip nil handles.","Prefer the GetIdString(this IEntity entity) overload, which already guards nil tokens and non-metadata entities.","When iterating handles, filter early: `if (handle.IsNil) continue;`."],"exampleFix":"// before\nforeach (var h in handles)\n    idStrings.Add(IdStringProvider.GetIdString(module, h));\n\n// after\nforeach (var h in handles)\n{\n    if (h.IsNil) continue;\n    idStrings.Add(IdStringProvider.GetIdString(module, h));\n}","handlingStrategy":"validation","validationCode":"if (handle.IsNil) return null; // or continue / skip\nvar id = IdStringProvider.GetIdString(module, handle);","typeGuard":"static bool IsComputableHandle(EntityHandle h) => !h.IsNil && h.Kind is HandleKind.TypeDefinition or HandleKind.FieldDefinition or HandleKind.MethodDefinition or HandleKind.PropertyDefinition or HandleKind.EventDefinition;","tryCatchPattern":null,"preventionTips":["Always pair any handle lookup with an IsNil check before computing its ID string.","Prefer GetIdString(this IEntity entity), which already rejects nil and non-metadata entities.","When iterating table rows, filter nil handles at the top of the loop."],"tags":["id-string","metadata","nil-handle","argument"],"backgroundTag":null,"analyzedSha":"60c08fcb74fcc183130f73c861ed35cf944d0bf1","analyzedAt":"2026-08-13T11:34:51.223Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}