NationalSecurityAgency/ghidra · error · AddressOutOfBoundsException

Range [%s:%x+%x] entirely exceeds space max

Error message

Range [%s:%x+%x] entirely exceeds space max

What it means

Thrown as AddressOutOfBoundsException by OpenTrace.toRange when the range's minimum offset is strictly greater than the address space's maximum address — i.e., the entire requested range lies beyond the high end of the space. This is distinct from the partial-overflow case, which only warns and clamps. The unsigned comparison means 64-bit offsets are compared correctly.

Source

Thrown at Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/app/plugin/core/debug/service/tracermi/OpenTrace.java:164

	}

	@Override
	public AddressRange toRange(AddrRange range, boolean required) {
		AddressSpace space = getSpace(range.getSpace(), required);
		if (space == null) {
			return null;
		}
		/**
		 * Clamp to only the valid addresses, but do at least warn.
		 */
		long minOffset = range.getOffset();
		if (Long.compareUnsigned(minOffset, space.getMinAddress().getOffset()) < 0) {
			Msg.warn(this, "Range [%s:%x+%x] partially exceeds space min. Clamping."
					.formatted(range.getSpace(), range.getOffset(), range.getExtend()));
			minOffset = space.getMinAddress().getOffset();
		}
		else if (Long.compareUnsigned(minOffset, space.getMaxAddress().getOffset()) > 0) {
			throw new AddressOutOfBoundsException("Range [%s:%x+%x] entirely exceeds space max"
					.formatted(range.getSpace(), range.getOffset(), range.getExtend()));
		}
		long maxOffset = range.getOffset() + range.getExtend(); // Use the requested offset, not adjusted
		if (Long.compareUnsigned(maxOffset, space.getMaxAddress().getOffset()) > 0) {
			Msg.warn(this, "Range [%s:%x+%x] partially exceeds space max. Clamping."
					.formatted(range.getSpace(), range.getOffset(), range.getExtend()));
			maxOffset = space.getMaxAddress().getOffset();
		}
		else if (Long.compareUnsigned(maxOffset, space.getMinAddress().getOffset()) < 0) {
			throw new AddressOutOfBoundsException("Range [%s:%x+%x] entirely exceeds space min"
					.formatted(range.getSpace(), range.getOffset(), range.getExtend()));
		}
		Address min = space.getAddress(minOffset);
		Address max = space.getAddress(maxOffset);
		return new AddressRangeImpl(min, max);
	}

	public Register getRegister(String name, boolean required) {

View on GitHub (pinned to d5f144c24d)

Solutions

1. Verify the address space name in the range matches the target's actual memory space.
2. Ensure offsets fit within the space's bit-width (e.g., < 2^32 for a 32-bit space).
3. Check for arithmetic that may have overflowed or sign-extended a 32-bit value into 64 bits.

Example fix

// before
// range offset 0x1_0000_0000 in a 32-bit space -> throws

// after
// use an offset within the space, e.g. 0x0040_0000
range = AddrRange.newBuilder().setSpace("ram").setOffset(0x00400000).setExtend(0x100).build();

AddressSpace space = trace.getBaseAddressFactory().getAddressSpace(range.getSpace());
long min = range.getOffset();
if (Long.compareUnsigned(min, space.getMaxAddress().getOffset()) > 0) {
    throw new IllegalArgumentException("Range start beyond space max");
}

boolean isRangeWithinSpace(AddrRange range, AddressSpace space) {
    long min = range.getOffset();
    long max = range.getOffset() + range.getExtend();
    return Long.compareUnsigned(min, space.getMinAddress().getOffset()) >= 0
        && Long.compareUnsigned(max, space.getMaxAddress().getOffset()) <= 0;
}

When it happens

Trigger: A remote Trace RMI command specifies an AddrRange whose offset (in the given space) is beyond the space's max address. For example, an offset of 0x100000000 in a 32-bit space, or any range whose start exceeds the space ceiling. The min/max comparison is unsigned.

Common situations: 64-bit address passed against a 32-bit address space definition; arithmetic overflow producing a wrapped/huge offset; the wrong address space name used for the target; a target with a non-standard memory layout the trace language doesn't model correctly.

Related errors

• Address must be in the form 'host:port'
• Attempt to create existing memory
• Must set id or path
• Space does not exist
• Space must be a memory, register, or NO_ADDRESS space

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