CoplayDev/unity-mcp · error · ArgumentException

Unknown layer name: '{layerMaskStr}'. Use a valid layer name

Error message

Unknown layer name: '{layerMaskStr}'. Use a valid layer name or integer mask.

What it means

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.

Source

Thrown at MCPForUnity/Editor/Tools/Physics/PhysicsQueryOps.cs:804

                    instanceID = hit.collider.gameObject.GetInstanceIDCompat(),
                    collider_type = hit.collider.GetType().Name
                }
            };
        }

        private static int ResolveLayerMask(string layerMaskStr)
        {
            if (string.IsNullOrEmpty(layerMaskStr))
                return ~0; // All layers

            if (int.TryParse(layerMaskStr, out int mask))
                return mask;

            int layer = LayerMask.NameToLayer(layerMaskStr);
            if (layer >= 0)
                return 1 << layer;

            throw new ArgumentException($"Unknown layer name: '{layerMaskStr}'. Use a valid layer name or integer mask.");
        }
    }
}

View on GitHub (pinned to c21bf496bc)

Solutions

1. Check Project Settings > Tags and Layers and use the exact layer name as registered (case-sensitive).
2. If targeting multiple layers, pass an integer bitmask (e.g. '12' for layers 2 and 3 combined as 1<<2|1<<3).
3. List available layers first via a resource or tool call, then reference by exact name or index.
4. Verify spelling, capitalization, and that no leading/trailing whitespace is present.

Example fix

// before
params = {"layerMask": "Defult"}
// after
params = {"layerMask": "Default"}  // or integer: {"layerMask": "2"}

import subprocess, json

def validate_layer_name(layer_name: str) -> bool:
    """Check layer name is likely valid (non-empty, alphanumeric)."""
    if not layer_name:
        return True  # empty = all layers
    if layer_name.lstrip('-').isdigit():
        return True  # integer bitmask
    return len(layer_name) > 0 and not layer_name.startswith(' ')

try
{
    int mask = ResolveLayerMask(layerMaskStr);
}
catch (ArgumentException ex) when (ex.Message.StartsWith("Unknown layer name"))
{
    // Fall back to all layers or prompt user to specify a valid layer
    Debug.LogWarning($"Unknown layer '{layerMaskStr}', defaulting to all layers.");
    mask = ~0;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Color array must have 3 or 4 elements.
• Port must be positive.
• Port {port} is already in use.
• uid required
• provider returned a disallowed file type '.{ext}'

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/5820eb33c1a9f8df. Report an issue: GitHub.