NationalSecurityAgency/ghidra · error · TraceConflictedMappingException

Another mapping would conflict

Error message

Another mapping would conflict

What it means

Thrown as TraceConflictedMappingException by DBTraceStaticMappingManager.add when a newly added static mapping would overlap an existing mapping (same trace address range and overlapping lifespan) that points to a different static program or address. Trace mappings are required to be consistent: the same dynamic location over a given snap range cannot map to two different static locations.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/module/DBTraceStaticMappingManager.java:90

		mappingStore.invalidateCache();
	}

	@Override
	public void dbError(IOException e) {
		trace.dbError(e);
	}

	@Override
	public DBTraceStaticMapping add(AddressRange range, Lifespan lifespan, URL toProgramURL,
			String toAddress) throws TraceConflictedMappingException {
		Objects.requireNonNull(toProgramURL,
			"Program URL cannot be null. Program must be in a project to have a URL.");
		try (LockHold hold = LockHold.lock(lock.writeLock())) {
			DBTraceStaticMapping conflict =
				findAnyConflicting(range, lifespan, toProgramURL, toAddress);
			if (conflict != null) {
				// TODO: Find all conflicts?
				throw new TraceConflictedMappingException("Another mapping would conflict",
					Set.of(conflict));
			}
			// TODO: A more sophisticated coverage check?
			// TODO: Better coalescing
			// For now, just check if a single entry contains the would-be-new entry
			for (DBTraceStaticMapping covers : findAllOverlapping(range, lifespan)) {
				if (!covers.getTraceAddressRange().contains(range.getMinAddress())) {
					continue;
				}
				if (!covers.getTraceAddressRange().contains(range.getMaxAddress())) {
					continue;
				}
				if (!covers.getLifespan().encloses(lifespan)) {
					continue;
				}
				return covers;
			}
			DBTraceStaticMapping mapping = mappingStore.create();

View on GitHub (pinned to d5f144c24d)

Solutions

1. Before adding, call findAnyConflicting (or query existing overlapping mappings) and remove or narrow the conflicting mapping first.
2. Use a non-overlapping lifespan or address range so the new mapping does not collide with the existing one.
3. If the new mapping is correct, delete the old conflicting mapping via its delete() method, then retry add().

Example fix

// before
mappingManager.add(range, lifespan, programURL, staticAddr); // throws if conflict

// after
DBTraceStaticMapping conflict = mappingManager.findAnyConflicting(range, lifespan, programURL, staticAddr);
if (conflict != null) {
    conflict.delete();
}
mappingManager.add(range, lifespan, programURL, staticAddr);

// Check for conflicts before adding a mapping
DBTraceStaticMapping conflict =
    mappingManager.findAnyConflicting(range, lifespan, programURL, staticAddr);
if (conflict != null) {
    conflict.delete(); // remove or narrow the old mapping
}

try {
    mappingManager.add(range, lifespan, programURL, staticAddr);
} catch (TraceConflictedMappingException e) {
    // e.getConflicts() returns the conflicting mapping set
    for (DBTraceStaticMapping c : e.getConflicts()) {
        // decide: delete, narrow lifespan, or skip
    }
}

When it happens

Trigger: Calling add(range, lifespan, toProgramURL, toAddress) where findAnyConflicting detects an existing mapping over the same range+snap that maps to a different program URL or static address.

Common situations: Re-mapping a trace region to a different program after it was already mapped. Overlapping two module static mappings that disagree. Re-running an auto-mapping/import step without first clearing the old conflicting mapping. Loading a trace that already has mappings then adding new ones over the same addresses.

Related errors

• endpoint cannot be -1
• Address string should have at most one colon (:)
• Given bookmark is not present at this view's snap
• max < min: min={min},max={max}
• Conflicting mappings for {}

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