NationalSecurityAgency/ghidra · error · CodeUnitInsertionException

Code unit would extend beyond address space

Error message

Code unit would extend beyond address space

What it means

Thrown by DBTraceInstructionsView.create() when doCreate() throws an AddressOverflowException, which occurs when address.addNoWrap(length - 1) overflows the address space. The create() method catches the AddressOverflowException and re-throws it as a CodeUnitInsertionException with this message. This means the instruction's end address (address + length - 1) would exceed the maximum address of the address space.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/DBTraceInstructionsView.java:413

		// TODO: Ensure cached undefineds don't extend into defined stuff
		// TODO: Explicitly remove undefined from cache, or let weak refs take care of it?
		return created;
	}

	@Override
	public DBTraceInstruction create(Lifespan lifespan, Address address, TracePlatform platform,
			InstructionPrototype prototype, ProcessorContextView context, int forcedLengthOverride)
			throws CodeUnitInsertionException {
		InternalTracePlatform dbPlatform = space.manager.platformManager.assertMine(platform);
		try (LockHold hold = LockHold.lock(space.lock.writeLock())) {
			DBTraceInstruction created =
				doCreate(lifespan, address, dbPlatform, prototype, context, forcedLengthOverride);
			space.trace.setChanged(
				new TraceChangeRecord<>(TraceEvents.CODE_ADDED, space.space, created, created));
			return created;
		}
		catch (AddressOverflowException e) {
			throw new CodeUnitInsertionException("Code unit would extend beyond address space");
		}
	}

	/**
	 * Prepare to check a block for conflicts
	 * 
	 * @param startSnap the minimum snap for each instruction
	 * @param block the block of instructions
	 * @return an iterator for overlapping object pairs
	 */
	protected OverlappingObjectIterator<Instruction, CodeUnit> startCheckingBlock(long startSnap,
			InstructionBlock block) {
		Address startAddress = block.getStartAddress();
		CodeUnit found = space.definedUnits.getContaining(startSnap, startAddress);
		if (found != null) {
			startAddress = found.getAddress();
		}
		Iterator<Instruction> instructions = block.iterator();

View on GitHub (pinned to d5f144c24d)

Solutions

1. Check that address.addNoWrap(length - 1) does not throw AddressOverflowException before calling create().
2. Validate the address has enough room: addr.getOffset() + length - 1 <= addr.getAddressSpace().getMaxAddress().getOffset().
3. Use a shorter length or an earlier start address.
4. Catch CodeUnitInsertionException and check for this condition when it occurs near the address space boundary.

Example fix

// before
DBTraceInstruction instr = view.create(lifespan, addr, platform, proto, ctx, length);

// after
try {
    addr.addNoWrap(length - 1); // pre-check
} catch (AddressOverflowException e) {
    // adjust length or skip
    return;
}
DBTraceInstruction instr = view.create(lifespan, addr, platform, proto, ctx, length);

// Pre-check address space bounds
try {
    address.addNoWrap(length - 1);
} catch (AddressOverflowException e) {
    // would overflow; reduce length or skip
    length = (int)(address.getAddressSpace().getMaxAddress().getOffset() - address.getOffset() + 1);
    if (length <= 0) return; // no room at all
}

try {
    DBTraceInstruction instr = view.create(lifespan, addr, platform, proto, ctx, len);
} catch (CodeUnitInsertionException e) {
    if (e.getMessage().contains("beyond address space")) {
        // instruction too close to space boundary; reduce length or skip
    }
}

When it happens

Trigger: Calling create() with an address near the top of the address space and a non-zero instruction length such that address + length - 1 wraps or exceeds the address space boundary. For example, creating a 4-byte instruction at 0xFFFFFFFC in a 32-bit space (which is valid), but at 0xFFFFFFFE it would overflow.

Common situations: Disassembling the last bytes of a memory region near the address space boundary. Creating instructions with length overrides that push the end address beyond the space limit. Processing corrupted or malformed instruction data that yields unexpectedly large lengths.

Related errors

• Failed to read {len} bytes at {addr}
• Trace does not contain referenced instruction: ({getStartSna
• Instruction has incompatible prototype at: ({getStartSnap},{
• Code units cannot overlap
• Platform and prototype disagree in language

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