NationalSecurityAgency/ghidra · error · CodeUnitInsertionException

Code unit would extend beyond address space

Error message

Code unit would extend beyond address space

What it means

Thrown as CodeUnitInsertionException by createInstruction when constructing the address range addr..addr+length overflows the address space's maximum address. This happens when an instruction is placed near the end of an address space and its length would extend past the space boundary.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/program/AbstractDBTraceProgramViewListing.java:721

	@Override
	public PropertyMap<?> getPropertyMap(String propertyName) {
		// TODO Auto-generated method stub
		return null;
	}

	@Override
	public Instruction createInstruction(Address addr, InstructionPrototype prototype,
			MemBuffer memBuf, ProcessorContextView context, int forcedLengthOverride)
			throws CodeUnitInsertionException {
		int checkLengthOverride =
			InstructionDB.checkLengthOverride(forcedLengthOverride, prototype);
		int length = checkLengthOverride != 0 ? checkLengthOverride : prototype.getLength();
		AddressRange range;
		try {
			range = new AddressRangeImpl(addr, length);
		}
		catch (AddressOverflowException e) {
			throw new CodeUnitInsertionException("Code unit would extend beyond address space");
		}
		var mostRecent = program.memory.memoryManager.getViewMostRecentStateEntry(program.snap,
			range, StatePredicate.IS_KNOWN);
		long snap = mostRecent == null ? program.snap : mostRecent.getKey().getY2();
		return codeOperations.instructions()
				.create(Lifespan.nowOn(snap), addr, program.platform, prototype, context,
					forcedLengthOverride);
	}

	@Override
	public AddressSetView addInstructions(InstructionSet instructionSet, boolean overwrite)
			throws CodeUnitInsertionException {
		return codeOperations.instructions()
				.addInstructionSet(Lifespan.nowOn(program.snap), program.platform, instructionSet,
					overwrite);
	}

	@Override

View on GitHub (pinned to d5f144c24d)

Solutions

1. Check addr.getAddressSpace().getMaxAddress().subtract(addr) >= length-1 before creating the instruction.
2. Use a larger address space, or relocate the code so instructions do not abut the space boundary.
3. If the length is a forced override, validate that the override length fits the remaining space.

Example fix

// before
program.getListing().createInstruction(addr, proto, buf, ctx, forcedLen);

// after
long remaining = addr.getAddressSpace().getMaxAddress().subtract(addr);
if (remaining < length - 1) {
    // instruction would overflow; relocate or truncate
    return;
}
program.getListing().createInstruction(addr, proto, buf, ctx, forcedLen);

// Check the instruction fits within the address space before creating it
long maxOffset = addr.getAddressSpace().getMaxAddress().getOffset();
long addrOffset = addr.getOffset();
if (Long.compareUnsigned(maxOffset - addrOffset, length - 1) < 0) {
    // would overflow; relocate or abort
    return;
}

try {
    listing.createInstruction(addr, proto, buf, ctx, forcedLen);
} catch (CodeUnitInsertionException e) {
    // instruction placement failed (e.g. address-space overflow or conflict)
}

When it happens

Trigger: Calling createInstruction(addr, prototype, memBuf, context, forcedLengthOverride) where addr is within 'length' bytes of the address space's max address, causing new AddressRangeImpl(addr, length) to throw AddressOverflowException.

Common situations: Disassembling or manually placing instructions at the top of a small/overlay address space. Forcing a long instruction override near the end of RAM. Importing data that places code at the very last bytes of a register bank or truncated address space.

Related errors

• Space does not exist
• Memory addresses cannot be associated with a thread
• Total step count exceeds LONG_MAX
• No such address space: %s
• Address {address} is not in process {proc.GetProcessID()}

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