{"record":{"id":"5820eb33c1a9f8df","repo":"CoplayDev/unity-mcp","slug":"unknown-layer-name-layermaskstr-use-a-valid","errorCode":null,"errorMessage":"Unknown layer name: '{layerMaskStr}'. Use a valid layer name or integer mask.","messagePattern":"Unknown layer name: '(.+?)'\\. Use a valid layer name or integer mask\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MCPForUnity/Editor/Tools/Physics/PhysicsQueryOps.cs","lineNumber":804,"sourceCode":"                    instanceID = hit.collider.gameObject.GetInstanceIDCompat(),\n                    collider_type = hit.collider.GetType().Name\n                }\n            };\n        }\n\n        private static int ResolveLayerMask(string layerMaskStr)\n        {\n            if (string.IsNullOrEmpty(layerMaskStr))\n                return ~0; // All layers\n\n            if (int.TryParse(layerMaskStr, out int mask))\n                return mask;\n\n            int layer = LayerMask.NameToLayer(layerMaskStr);\n            if (layer >= 0)\n                return 1 << layer;\n\n            throw new ArgumentException($\"Unknown layer name: '{layerMaskStr}'. Use a valid layer name or integer mask.\");\n        }\n    }\n}\n","sourceCodeStart":786,"sourceCodeEnd":808,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/MCPForUnity/Editor/Tools/Physics/PhysicsQueryOps.cs#L786-L808","documentation":"Thrown by ResolveLayerMask in PhysicsQueryOps when the 'layerMask' string is non-empty, is not a parseable integer, and LayerMask.NameToLayer returns -1 (the name does not match any layer defined in Tag Manager). The method accepts an integer bitmask, a single layer name, or empty (all layers) — anything else is rejected.","triggerScenarios":"Calling a physics query tool (overlap_sphere, raycast, sphere_cast, etc.) with a layerMask parameter that references a layer name not defined in the project's Layer settings. Typo in layer name, or using a layer name from a different project.","commonSituations":"Layer renamed or removed in Project Settings > Tags and Layers; case-sensitivity mismatch (LayerMask.NameToLayer is case-sensitive); using a built-in layer name that doesn't exist; passing a human-readable label instead of the registered layer name.","solutions":["Check Project Settings > Tags and Layers and use the exact layer name as registered (case-sensitive).","If targeting multiple layers, pass an integer bitmask (e.g. '12' for layers 2 and 3 combined as 1<<2|1<<3).","List available layers first via a resource or tool call, then reference by exact name or index.","Verify spelling, capitalization, and that no leading/trailing whitespace is present."],"exampleFix":"// before\nparams = {\"layerMask\": \"Defult\"}\n// after\nparams = {\"layerMask\": \"Default\"}  // or integer: {\"layerMask\": \"2\"}","handlingStrategy":"validation","validationCode":"import subprocess, json\n\ndef validate_layer_name(layer_name: str) -> bool:\n    \"\"\"Check layer name is likely valid (non-empty, alphanumeric).\"\"\"\n    if not layer_name:\n        return True  # empty = all layers\n    if layer_name.lstrip('-').isdigit():\n        return True  # integer bitmask\n    return len(layer_name) > 0 and not layer_name.startswith(' ')","typeGuard":null,"tryCatchPattern":"try\n{\n    int mask = ResolveLayerMask(layerMaskStr);\n}\ncatch (ArgumentException ex) when (ex.Message.StartsWith(\"Unknown layer name\"))\n{\n    // Fall back to all layers or prompt user to specify a valid layer\n    Debug.LogWarning($\"Unknown layer '{layerMaskStr}', defaulting to all layers.\");\n    mask = ~0;\n}","preventionTips":["Use exact layer names from Project Settings > Tags and Layers (case-sensitive).","Prefer integer bitmasks for programmatic calls to avoid name-lookup ambiguity.","Cache the layer list at the start of a session and reference by name from that list.","Avoid hardcoding layer names that may differ across projects."],"tags":["physics","layer-mask","validation","tag-manager"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}