NationalSecurityAgency/ghidra · error · IllegalArgumentException

Register {register} is not mapped

Error message

Register {register} is not mapped

What it means

getConventionalRegisterRange maps the register's address range from guest to host via mapGuestToHost(TraceRegisterUtils.rangeForRegister(register)); if the result is null it throws IllegalArgumentException("Register X is not mapped"). The guest register's address has no host-side mapping covering it, so it cannot be translated.

Source

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

	/**
	 * Get the entry's key in the table as an integer
	 * 
	 * @return the key
	 */
	int getIntKey();

	DBTraceGuestLanguage getLanguageEntry();

	@Override
	default AddressFactory getAddressFactory() {
		return TracePlatform.super.getAddressFactory();
	}

	@Override
	default AddressRange getConventionalRegisterRange(AddressSpace space, Register register) {
		AddressRange result = mapGuestToHost(TraceRegisterUtils.rangeForRegister(register));
		if (result == null) {
			throw new IllegalArgumentException("Register " + register + " is not mapped");
		}
		if (space == null) {
			return result;
		}
		if (register.getAddressSpace().isRegisterSpace()) {
			if (result.getAddressSpace() != space.getPhysicalSpace()) {
				throw new IllegalArgumentException(
					"Register " + register + " does not map to space " + space +
						"'s physical space (" + space.getPhysicalSpace() + ")");
			}
			return new AddressRangeImpl(
				space.getOverlayAddress(result.getMinAddress()),
				space.getOverlayAddress(result.getMaxAddress()));
		}
		if (result.getAddressSpace() != space) {
			throw new IllegalArgumentException(
				"Memory-mapped register " + register + " does not map to space " + space);
		}

View on GitHub (pinned to d5f144c24d)

Solutions

1. Establish a register-bank mapping via addMappedRange over the register address range first.
2. Pre-check mapGuestToHost(register.getAddress()) != null before calling getConventionalRegisterRange.
3. Query a register known to be within an existing mapping.

Example fix

// before
AddressRange r = platform.getConventionalRegisterRange(space, reg);

// after
if (platform.mapGuestToHost(reg.getAddress()) == null) {
    // ensure register bank is mapped first
    platform.addMappedRange(hostBase, reg.getAddress(), reg.getNumBytes());
}
AddressRange r = platform.getConventionalRegisterRange(space, reg);

if (platform.mapGuestToHost(register.getAddress()) == null) {
    // map the register bank (addMappedRange) before querying
}

static boolean registerIsMapped(InternalTracePlatform p, Register r) {
    return p.mapGuestToHost(r.getAddress()) != null;
}

try { return platform.getConventionalRegisterRange(space, register); }
catch (IllegalArgumentException e) { /* register not mapped; map it first */ }

When it happens

Trigger: Calling getConventionalRegisterRange on a guest platform register before any addMappedRange covers the register bank; querying a register on a partially-mapped guest platform; newly-added guest platform without register mapping.

Common situations: Querying registers on a guest that hasn't had its register bank mapped to host memory; partial mappings covering some registers but not the queried one.

Related errors

• Guest address ${addr} is not mapped, or the mapped address d
• This mapper cannot handle Harvard guests
• The function for the frame is no longer present in the mappe
• Cannot find static program for frame ({pc}={pcVal})
• Unknown register or label: '{nm}'

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