{"record":{"id":"9cebeb8e5d134bf6","repo":"NationalSecurityAgency/ghidra","slug":"range-overlaps-existing-host-mapped-range-s-for-t","errorCode":null,"errorMessage":"Range overlaps existing host mapped range(s) for this guest language","messagePattern":"Range overlaps existing host mapped range\\(s\\) for this guest language","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/guest/DBTraceGuestPlatform.java","lineNumber":270,"sourceCode":"\tpublic TraceBasedDataTypeManager getDataTypeManager() {\n\t\treturn dataTypeManager;\n\t}\n\n\t@Override\n\tpublic void delete(TaskMonitor monitor) throws CancelledException {\n\t\tmanager.deleteGuestPlatform(this, monitor);\n\t\t// TODO: Delete language once no platform uses it?\n\t}\n\n\t@Override\n\tpublic DBTraceGuestPlatformMappedRange addMappedRange(Address hostStart, Address guestStart,\n\t\t\tlong length) throws AddressOverflowException {\n\t\tDBTraceGuestPlatformMappedRange mappedRange;\n\t\ttry (LockHold hold = LockHold.lock(manager.lock.writeLock())) {\n\t\t\tAddress hostEnd = hostStart.addWrap(length - 1);\n\t\t\tif (hostAddressSet.intersects(hostStart, hostEnd)) {\n\t\t\t\t// TODO: Check for compatibility and extend?\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Range overlaps existing host mapped range(s) for this guest language\");\n\t\t\t}\n\t\t\tAddress guestEnd = guestStart.addWrap(length - 1);\n\t\t\tif (guestAddressSet.intersects(guestStart, guestEnd)) {\n\t\t\t\tthrow new IllegalArgumentException(\"Range overlaps existing guest mapped range(s)\");\n\t\t\t}\n\t\t\tmappedRange = manager.rangeMappingStore.create();\n\t\t\tmappedRange.set(hostStart, this, guestStart, length);\n\t\t\trangesByHostAddress.put(hostStart, mappedRange);\n\t\t\trangesByGuestAddress.put(guestStart, mappedRange);\n\t\t\thostAddressSet.add(mappedRange.getHostRange());\n\t\t\tguestAddressSet.add(mappedRange.getGuestRange());\n\t\t}\n\t\tmanager.trace.setChanged(new TraceChangeRecord<>(TraceEvents.PLATFORM_MAPPING_ADDED,\n\t\t\thostStart.getAddressSpace(), this, null, mappedRange));\n\t\treturn mappedRange;\n\t}\n","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/guest/DBTraceGuestPlatform.java#L252-L288","documentation":"addMappedRange computes hostEnd = hostStart.addWrap(length-1) and checks hostAddressSet.intersects(hostStart, hostEnd). If the new host span overlaps any already-mapped host span for this guest language, it throws IllegalArgumentException(\"Range overlaps existing host mapped range(s)\"). Host-side regions must be disjoint within a guest platform.","triggerScenarios":"Mapping a second guest range whose host window overlaps an existing one for the same platform; reusing host addresses; an off-by-one in length producing a one-byte overlap with an adjacent range.","commonSituations":"Building overlapping guest-to-host mappings during emulation setup; reconfiguring mappings without clearing prior ones; miscomputed lengths.","solutions":["Check hostAddressSet.intersects(hostStart, hostEnd) before calling addMappedRange.","Choose a non-overlapping host base address.","Delete the conflicting prior mapped range first (the code's TODO notes possible extend support)."],"exampleFix":"// before\nplatform.addMappedRange(hostStart, guestStart, length);\n\n// after\nAddress hostEnd = hostStart.addWrap(length - 1);\nif (hostAddressSet.intersects(hostStart, hostEnd)) {\n    hostStart = hostAddressSet.getMaxAddress().add(1);\n}\nplatform.addMappedRange(hostStart, guestStart, length);","handlingStrategy":"validation","validationCode":"Address hostEnd = hostStart.addWrap(length - 1);\nif (hostAddressSet.intersects(hostStart, hostEnd)) {\n    // pick a new host base or remove the conflicting range\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Track allocated host spans and allocate from the next free base.","Clear existing mapped ranges before reconfiguring a platform.","Double-check length arithmetic to avoid one-byte adjacency overlaps."],"tags":["memory-mapping","overlap","guest-platform"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}