NationalSecurityAgency/ghidra · error · IllegalArgumentException

Invalid address space for overlay: {}

Error message

Invalid address space for overlay: {}

What it means

doCreateOverlaySpace validates the proposed base address space via factory.isValidOverlayBaseSpace(base). If false, it throws IllegalArgumentException("Invalid address space for overlay"). This enforces the invariant that overlays sit on real physical memory spaces: an overlay space, register space, constant space, or other non-physical space is rejected as a base.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/address/DBTraceOverlaySpaceAdapter.java:255

		factory.refreshStaleOverlayStatus();
	}

	private boolean isCompatibleOverlay(ProgramOverlayAddressSpace os, DBTraceOverlaySpaceEntry ent,
			ProgramAddressFactory factory) {
		AddressSpace baseSpace = factory.getAddressSpace(ent.baseSpace);
		if (baseSpace == null) {
			// Error condition should be handled better - language may have dropped original base space
			throw new RuntimeException("Base space for overlay not found: " + ent.baseSpace);
		}
		return baseSpace == os.getOverlayedSpace();
	}

	protected AddressSpace doCreateOverlaySpace(String name, AddressSpace base)
			throws DuplicateNameException {
		TraceAddressFactory factory = trace.getInternalAddressFactory();

		if (!factory.isValidOverlayBaseSpace(base)) {
			throw new IllegalArgumentException(
				"Invalid address space for overlay: " + base.getName());
		}

		if (factory.getAddressSpace(name) != null) {
			throw new DuplicateNameException(
				"Overlay space '" + name + "' duplicates name of another address space");
		}

		DBTraceOverlaySpaceEntry ent = overlayStore.create();
		ProgramOverlayAddressSpace space = factory.addOverlaySpace(ent.getKey(), name, base);

		// Only if it succeeds do we store the record
		ent.set(space.getName(), base.getName());
		trace.updateViewsAddSpaceBlock(space);
		trace.setChanged(
			new TraceChangeRecord<>(TraceEvents.OVERLAY_ADDED, space, trace, null, space));
		return space;
	}

View on GitHub (pinned to d5f144c24d)

Solutions

1. Pass a physical memory address space from the base address factory.
2. Derive the base from a real address: addr.getAddressSpace().getPhysicalSpace().
3. Pre-check with factory.isValidOverlayBaseSpace(base) and skip/handle when false.

Example fix

// before
AddressSpace base = someOverlayAddr.getAddressSpace();
trace.createOverlayAddressSpace("ovl", base);

// after
AddressSpace base = someAddr.getAddressSpace().getPhysicalSpace();
if (!factory.isValidOverlayBaseSpace(base)) {
    throw new IllegalStateException("not a valid overlay base");
}
trace.createOverlayAddressSpace("ovl", base);

AddressSpace base = addr.getAddressSpace().getPhysicalSpace();
if (!factory.isValidOverlayBaseSpace(base)) {
    // not a valid overlay base; do not call createOverlayAddressSpace
}

static boolean isOverlayBaseOk(TraceAddressFactory f, AddressSpace s) {
    return s != null && f.isValidOverlayBaseSpace(s);
}

When it happens

Trigger: Calling createOverlayAddressSpace / getOrCreateOverlayAddressSpace / doCreateOverlaySpace passing an overlay space (e.g. the result of a previous create), a register space, a constant space, or another non-physical space as base.

Common situations: Programmatic batch overlay creation accidentally chaining the returned overlay as the next base; mistaking a register-mapped or constant space for a memory space; passing a space obtained from an address without resolving its physical space.

Related errors

• No such address space: %s
• Return address must be in {}
• Return address must be in {}
• Range [%s:%x+%x] entirely exceeds space min
• AddressSpace '{}' is not in this trace (language={})

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