What causes "Code units cannot overlap" in NationalSecurityAgency/ghidra?

Delete the existing code unit at that address+snap before creating: codeUnit.delete() or disassembleClear().

NationalSecurityAgency/ghidra · error · CodeUnitInsertionException

Code units cannot overlap

Error message

Code units cannot overlap

What it means

Thrown early in DBTraceDefinedDataView.create() when the start address is already occupied by a defined unit at the requested startSnap — the undefinedData view does not cover the single-byte range at (startSnap, address). This is the initial overlap check performed before data type resolution; it catches the case where another instruction or data unit already exists at the exact start address before any type processing happens.

Source

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

		return false;
	}

	@Override
	public DBTraceDataAdapter create(Lifespan lifespan, Address address, TracePlatform platform,
			DataType origType, int origLength) throws CodeUnitInsertionException {
		if (platform.getTrace() != getTrace() ||
			!(platform instanceof InternalTracePlatform iPlatform)) {
			throw new IllegalArgumentException("Platform is not part of this trace");
		}
		try (LockHold hold = LockHold.lock(space.lock.writeLock())) {
			DBTraceMemorySpace memSpace = space.trace.getMemoryManager().get(space.space, true);
			// NOTE: User-given length could be ignored....
			// Check start address first. After I know length, I can check for other existing units
			long startSnap = lifespan.lmin();
			if (!space.undefinedData.coversRange(Lifespan.at(startSnap),
				new AddressRangeImpl(address, address))) {
				// TODO: Figure out the conflicting unit?
				throw new CodeUnitInsertionException("Code units cannot overlap");
			}

			DataType dataType;
			int length;
			if (origType instanceof FactoryDataType) {
				MemBuffer buffer = memSpace.getBufferAt(startSnap, address);
				FactoryDataType fdt = (FactoryDataType) origType;
				dataType = fdt.getDataType(buffer);
				length = -1;
			}
			else {
				dataType = origType;
				length = origLength;
			}

			if (dataType == null) {
				throw new CodeUnitInsertionException("Failed to resolve data type");
			}

View on GitHub (pinned to d5f144c24d)

Solutions

Delete the existing code unit at that address+snap before creating: codeUnit.delete() or disassembleClear().
Use a different address or snapshot range.
Check view.getContaining(startSnap, address) before creating and handle the conflict.

Example fix

// before
view.create(Lifespan.span(0, 10), address, platform, dataType); // address already defined

// after — clear existing unit first
CodeUnit existing = view.getContaining(0, address);
if (existing != null) {
    existing.delete();
}
view.create(Lifespan.span(0, 10), address, platform, dataType);

Defensive patterns

Strategy: validation

Validate before calling

// Check if the start address is already defined before creating
long startSnap = lifespan.lmin();
if (!space.undefinedData.coversRange(Lifespan.at(startSnap),
        new AddressRangeImpl(address, address))) {
    // Address is occupied — clear or skip
    CodeUnit existing = view.getContaining(startSnap, address);
    if (existing != null) existing.delete();
}
view.create(lifespan, address, platform, dataType, length);

Try / catch

try {
    view.create(lifespan, address, platform, dataType, length);
} catch (CodeUnitInsertionException e) {
    if (e.getMessage().equals("Code units cannot overlap")) {
        CodeUnit existing = view.getContaining(lifespan.lmin(), address);
        if (existing != null) {
            existing.delete();
            view.create(lifespan, address, platform, dataType, length);
        }
    } else {
        throw e;
    }
}

Prevention

Check view.getContaining(startSnap, address) before creating data units.
Clear existing units at the target address before bulk annotations.
Design scripts to handle pre-existing units gracefully (overwrite or skip).

When it happens

Trigger: Calling view.create() at an address+snap where an existing code unit (instruction or data) already starts or covers that address. The check space.undefinedData.coversRange(Lifespan.at(startSnap), [address, address]) fails because the address is already defined.

Common situations: Creating data at an address that already has an instruction; creating overlapping data units; not clearing old units before re-annotating; script that iterates and creates data without checking for conflicts.

Related errors

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