NationalSecurityAgency/ghidra · error · IllegalArgumentException

Guest address {guestAddress} is not mapped

Error message

Guest address {guestAddress} is not mapped

What it means

Thrown as IllegalArgumentException by RW_TRACE.setVariable (ControlMode.java:230-234) when TracePlatform.mapGuestToHost(guestAddress) returns null. In RW_TRACE (Control Trace) mode, variable edits are written to the live trace snapshot; a guest address with no host-side mapping cannot be located, so the edit is rejected before opening the transaction.

Source

Thrown at Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/control/ControlMode.java:232

		public boolean canEdit(DebuggerCoordinates coordinates) {
			return coordinates.getTrace() != null;
		}

		@Override
		public boolean isVariableEditable(DebuggerCoordinates coordinates, Address address,
				int length) {
			return address.isMemoryAddress() || coordinates.getThread() != null;
		}

		@Override
		public CompletableFuture<Void> setVariable(PluginTool tool,
				DebuggerCoordinates coordinates, Address guestAddress, byte[] data) {
			Trace trace = coordinates.getTrace();
			TracePlatform platform = platformFor(coordinates, guestAddress);
			long snap = coordinates.getViewSnap();
			Address hostAddress = platform.mapGuestToHost(guestAddress);
			if (hostAddress == null) {
				throw new IllegalArgumentException(
					"Guest address " + guestAddress + " is not mapped");
			}
			TraceMemoryOperations memOrRegs;
			Address overlayAddress;
			try (Transaction tx = trace.openTransaction("Edit Variable")) {
				if (hostAddress.isRegisterAddress()) {
					TraceThread thread = coordinates.getThread();
					if (thread == null) {
						throw new IllegalArgumentException("Register edits require a thread.");
					}
					TraceMemorySpace regs = trace.getMemoryManager()
							.getMemoryRegisterSpace(thread, coordinates.getFrame(),
								true);
					memOrRegs = regs;
					overlayAddress = regs.getAddressSpace().getOverlayAddress(hostAddress);
				}
				else {
					memOrRegs = trace.getMemoryManager();

View on GitHub (pinned to d5f144c24d)

Solutions

1. Confirm the guest address is mapped for the active platform: check platform.mapGuestToHost(addr) != null before editing.
2. Record/refresh memory regions so the mapping exists, then retry the edit.
3. Switch to a platform whose mapping covers the address, or edit the equivalent host address directly.

Example fix

// before
RW_TRACE.setVariable(tool, coordinates, guestAddress, data);  // mapGuestToHost == null

// after
Address host = platform.mapGuestToHost(guestAddress);
if (host == null) {
    throw new IllegalStateException("no mapping for " + guestAddress);
}
RW_TRACE.setVariable(tool, coordinates, guestAddress, data);

Address host = platform.mapGuestToHost(guestAddress);
if (host == null) {
    throw new IllegalStateException("no host mapping for " + guestAddress);
}

boolean isMapped(TracePlatform platform, Address guestAddress) {
    return platform.mapGuestToHost(guestAddress) != null;
}

try {
    mode.setVariable(tool, coordinates, guestAddress, data);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is not mapped")) {
        // refresh mappings or switch platform, then retry
    } else throw e;
}

When it happens

Trigger: Calling setVariable on ControlMode.RW_TRACE with a guestAddress that the platform cannot translate (mapGuestToHost == null): an address in an unmapped overlay, a guest address for a platform with no address mapping configured, or an address space not present in the current platform.

Common situations: Multi-platform traces where the active platform lacks a mapping for the given guest space; editing before memory regions are recorded/mapped; a stale trace where mappings were not refreshed after a module load.

Related errors

• Register edits require a thread.
• Cannot emulate using a Fixed Program View
• Emulator edits require a thread.
• Unsupported value: {}
• Invalid value for {}

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