{"record":{"id":"9f36400a45da2c1f","repo":"antlr/antlr4","slug":"labels-cannot-be-null-9f3640","errorCode":null,"errorMessage":"labels cannot be null","messagePattern":"labels cannot be null","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"runtime/Python3/src/antlr4/tree/ParseTreeMatch.py","lineNumber":39,"sourceCode":"    #\n    # @param tree The parse tree to match against the pattern.\n    # @param pattern The parse tree pattern.\n    # @param labels A mapping from label names to collections of\n    # {@link ParseTree} objects located by the tree pattern matching process.\n    # @param mismatchedNode The first node which failed to match the tree\n    # pattern during the matching process.\n    #\n    # @exception IllegalArgumentException if {@code tree} is {@code null}\n    # @exception IllegalArgumentException if {@code pattern} is {@code null}\n    # @exception IllegalArgumentException if {@code labels} is {@code null}\n    #\n    def __init__(self, tree:ParseTree, pattern:ParseTreePattern, labels:dict, mismatchedNode:ParseTree):\n        if tree is None:\n            raise Exception(\"tree cannot be null\")\n        if pattern is None:\n            raise Exception(\"pattern cannot be null\")\n        if labels is None:\n            raise Exception(\"labels cannot be null\")\n        self.tree = tree\n        self.pattern = pattern\n        self.labels = labels\n        self.mismatchedNode = mismatchedNode\n\n    #\n    # Get the last node associated with a specific {@code label}.\n    #\n    # <p>For example, for pattern {@code <id:ID>}, {@code get(\"id\")} returns the\n    # node matched for that {@code ID}. If more than one node\n    # matched the specified label, only the last is returned. If there is\n    # no node associated with the label, this returns {@code null}.</p>\n    #\n    # <p>Pattern tags like {@code <ID>} and {@code <expr>} without labels are\n    # considered to be labeled with {@code ID} and {@code expr}, respectively.</p>\n    #\n    # @param label The label to check.\n    #","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/antlr/antlr4/blob/7d5770395bb7b02eb56e7c62662cb1d7c08f42a3/runtime/Python3/src/antlr4/tree/ParseTreeMatch.py#L21-L57","documentation":"Thrown by the ParseTreeMatch constructor in the Python3 runtime when the labels dict is None. ParseTreeMatch is the result object returned by ParseTreePattern.match() and records which pattern labels mapped to which parse-tree nodes. This error is a defensive precondition check; normal users get a ParseTreeMatch from the matcher and never construct one with None labels.","triggerScenarios":"Directly instantiating ParseTreeMatch(tree, pattern, None, mismatchedNode) from Python code, or a subclass/wrapper that passes an uninitialized labels dict. It cannot fire via ParseTreePattern.match(), which always builds the labels dict itself.","commonSituations":"Manually assembling a match result for unit tests, porting code from the Java runtime and forgetting that Python uses None checks, or partial initialization where labels was never populated.","solutions":["Do not construct ParseTreeMatch yourself; call pattern.match(tree) which builds a valid labels dict internally","If you must construct it, pass at minimum an empty dict {} instead of None","Audit wrappers/subclasses for a labels argument that can be None and default it to {}"],"exampleFix":"# before\nm = ParseTreeMatch(tree, pattern, None, mismatchNode)\n\n# after\nfrom antlr4.tree.ParseTreeMatch import ParseTreeMatch\nm = ParseTreeMatch(tree, pattern, {}, mismatchNode)","handlingStrategy":"validation","validationCode":"labels = labels if labels is not None else {}\nm = ParseTreeMatch(tree, pattern, labels, mismatchedNode)","typeGuard":"def has_labels(labels) -> bool:\n    return isinstance(labels, dict)","tryCatchPattern":null,"preventionTips":["Prefer pattern.match(tree) over constructing ParseTreeMatch directly","Default the labels argument to {} in wrappers"],"tags":["antlr","python","parse-tree-matching","precondition"],"backgroundTag":null,"analyzedSha":"7d5770395bb7b02eb56e7c62662cb1d7c08f42a3","analyzedAt":"2026-08-14T14:47:56.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}