NationalSecurityAgency/ghidra · error · IllegalArgumentException

Range overlaps existing guest mapped range(s)

Error message

Range overlaps existing guest mapped range(s)

What it means

After the host-overlap check in addMappedRange, the code computes guestEnd and tests guestAddressSet.intersects(guestStart, guestEnd); overlap on the guest side throws IllegalArgumentException("Range overlaps existing guest mapped range(s)"). Guest windows for a platform must also be mutually disjoint.

Source

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

	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;
	}

	protected Address computeNextRegisterMin() {
		Address regMax = manager.hostPlatform.getLanguage()
				.getAddressFactory()
				.getRegisterSpace()
				.getMaxAddress();

View on GitHub (pinned to d5f144c24d)

Solutions

1. Verify the guest range is disjoint from guestAddressSet before mapping.
2. Adjust guestStart and/or length to avoid overlap.
3. Remove the conflicting prior guest mapping first.

Example fix

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

// after
Address guestEnd = guestStart.addWrap(length - 1);
if (guestAddressSet.intersects(guestStart, guestEnd)) {
    throw new IllegalStateException("guest range conflicts; remove existing first");
}
platform.addMappedRange(hostStart, guestStart, length);

Address guestEnd = guestStart.addWrap(length - 1);
if (guestAddressSet.intersects(guestStart, guestEnd)) {
    // adjust guestStart/length or remove the conflicting prior mapping
}

When it happens

Trigger: Adding a second mapping whose guest span overlaps an existing one for the same platform; re-mapping guest addresses already covered.

Common situations: Emulation reconfiguration that reuses guest addresses; partial cleanup leaving a prior guest range in place.

Related errors

• Range overlaps existing host mapped range(s) for this guest
• 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/ce1b5f8f4e5ad21b. Report an issue: GitHub.