NationalSecurityAgency/ghidra · error · IllegalStateException

Given register is not mapped to the host, or it's not in the

Error message

Given register is not mapped to the host, or it's not in the guest language

What it means

Thrown by addRegisterMapOverride when mapGuestToHost(register.getAddress()) returns null, meaning the register's address could not be translated from the guest platform to the host platform. This indicates either the register is not part of the guest language at all, or the guest-to-host register mapping table has no entry for this register's address. An override cannot be created because there is no host address to anchor the label symbol to.

Source

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

			container.getCanonicalPath(), register);
	}

	@Override
	default PathFilter getConventionalRegisterPath(AddressSpace space, Register register) {
		KeyPath path = KeyPath.parse(space.getName());
		TraceObjectSchema rootSchema = getTrace().getObjectManager().getRootSchema();
		if (rootSchema == null) {
			return null;
		}
		TraceObjectSchema schema = rootSchema.getSuccessorSchema(path);
		return getConventionalRegisterPath(schema, path, register);
	}

	@Override
	default TraceLabelSymbol addRegisterMapOverride(Register register, String objectName) {
		Address hostAddr = mapGuestToHost(register.getAddress());
		if (hostAddr == null) {
			throw new IllegalStateException(
				"Given register is not mapped to the host, or it's not in the guest language");
		}
		try (LockHold hold = getTrace().lockWrite()) {
			TraceSymbolManager symbolManager = getTrace().getSymbolManager();
			TraceNamespaceSymbol globals = symbolManager.getGlobalNamespace();
			TraceNamespaceSymbolView namespaces = symbolManager.namespaces();
			String regMap = regMap(register);
			TraceNamespaceSymbol nsRegMap = namespaces.getGlobalNamed(regMap);
			if (nsRegMap == null) {
				nsRegMap = namespaces.add(regMap, globals, SourceType.USER_DEFINED);
			}
			TraceLabelSymbol exists = symbolManager.labels()
					.getChildWithNameAt(objectName, getIntKey(), hostAddr, nsRegMap);
			if (exists != null) {
				return exists;
			}
			return symbolManager.labels()
					.create(0, hostAddr, objectName, nsRegMap, SourceType.USER_DEFINED);

View on GitHub (pinned to d5f144c24d)

Solutions

1. Obtain the Register from the guest platform's language: platform.getLanguage().getRegister(name), not the host language.
2. Verify the register exists in the guest language via platform.getLanguage().getRegisters() before calling addRegisterMapOverride.
3. If the register is genuinely host-only and you want to expose it, register it in the guest language's mapping table first.

Example fix

// before
Register reg = hostLanguage.getRegister("XMM0");
platform.addRegisterMapOverride(reg, "xmm0");

// after — use the guest platform's own register
Register reg = platform.getLanguage().getRegister("XMM0");
if (reg != null) {
    platform.addRegisterMapOverride(reg, "xmm0");
}

// Verify the register maps to host before calling addRegisterMapOverride
Address hostAddr = platform.mapGuestToHost(register.getAddress());
if (hostAddr == null) {
    // Register is not mapped — do not call addRegisterMapOverride
    throw new IllegalStateException("Register " + register + " has no host mapping");
}
platform.addRegisterMapOverride(register, objectName);

static boolean registerIsMappedToHost(TracePlatform platform, Register register) {
    return platform.mapGuestToHost(register.getAddress()) != null;
}

try {
    platform.addRegisterMapOverride(register, objectName);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("not mapped to the host")) {
        // Register is not in the guest language — skip or log
        Msg.warn(MyClass.class, "Cannot override unmapped register: " + register);
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling platform.addRegisterMapOverride(register, objectName) where 'register' does not exist in the guest language's register context, or the guest platform has no register mapping configured for it. This occurs when you pass a host-only register to a guest platform's override API, or when the guest language has not been fully mapped to the host.

Common situations: Using a Register object obtained from the host language rather than the guest language; guest language definition missing register mappings; attempting to override a register that was removed in a newer .sla/.sleigh file; calling addRegisterMapOverride before the platform's register mappings are initialized.

Related errors

• Register {register} does not map to space {space}'s physical
• Memory-mapped register {register} does not map to space {spa
• Invalid byte_order: {}
• Cannot convert {}'s value: '{}', type: '{}'
• No register mapper

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