NationalSecurityAgency/ghidra · error · IllegalArgumentException

Range overlaps existing host mapped range(s) for this guest

Error message

Range overlaps existing host mapped range(s) for this guest language

What it means

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.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/guest/DBTraceGuestPlatform.java:270

	public TraceBasedDataTypeManager getDataTypeManager() {
		return dataTypeManager;
	}

	@Override
	public void delete(TaskMonitor monitor) throws CancelledException {
		manager.deleteGuestPlatform(this, monitor);
		// TODO: Delete language once no platform uses it?
	}

	@Override
	public DBTraceGuestPlatformMappedRange addMappedRange(Address hostStart, Address guestStart,
			long length) throws AddressOverflowException {
		DBTraceGuestPlatformMappedRange mappedRange;
		try (LockHold hold = LockHold.lock(manager.lock.writeLock())) {
			Address hostEnd = hostStart.addWrap(length - 1);
			if (hostAddressSet.intersects(hostStart, hostEnd)) {
				// TODO: Check for compatibility and extend?
				throw new IllegalArgumentException(
					"Range overlaps existing host mapped range(s) for this guest language");
			}
			Address guestEnd = guestStart.addWrap(length - 1);
			if (guestAddressSet.intersects(guestStart, guestEnd)) {
				throw new IllegalArgumentException("Range overlaps existing guest mapped range(s)");
			}
			mappedRange = manager.rangeMappingStore.create();
			mappedRange.set(hostStart, this, guestStart, length);
			rangesByHostAddress.put(hostStart, mappedRange);
			rangesByGuestAddress.put(guestStart, mappedRange);
			hostAddressSet.add(mappedRange.getHostRange());
			guestAddressSet.add(mappedRange.getGuestRange());
		}
		manager.trace.setChanged(new TraceChangeRecord<>(TraceEvents.PLATFORM_MAPPING_ADDED,
			hostStart.getAddressSpace(), this, null, mappedRange));
		return mappedRange;
	}

View on GitHub (pinned to d5f144c24d)

Solutions

1. Check hostAddressSet.intersects(hostStart, hostEnd) before calling addMappedRange.
2. Choose a non-overlapping host base address.
3. Delete the conflicting prior mapped range first (the code's TODO notes possible extend support).

Example fix

// before
platform.addMappedRange(hostStart, guestStart, length);

// after
Address hostEnd = hostStart.addWrap(length - 1);
if (hostAddressSet.intersects(hostStart, hostEnd)) {
    hostStart = hostAddressSet.getMaxAddress().add(1);
}
platform.addMappedRange(hostStart, guestStart, length);

Address hostEnd = hostStart.addWrap(length - 1);
if (hostAddressSet.intersects(hostStart, hostEnd)) {
    // pick a new host base or remove the conflicting range
}

When it happens

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

Common situations: Building overlapping guest-to-host mappings during emulation setup; reconfiguring mappings without clearing prior ones; miscomputed lengths.

Related errors

• Range overlaps existing guest mapped range(s)
• Address {address} is not in process {proc}
• Address {address} is not in inferior {inf.num}
• No memory mapper
• Platform table is corrupt. Missing language ${langKey}

AI-assisted analysis of NationalSecurityAgency/ghidra@d5f144c24d (2026-08-14). Data as JSON: /api/errors/9cebeb8e5d134bf6. Report an issue: GitHub.