NationalSecurityAgency/ghidra · error · AddressTranslationException

The specified source address range never had an external add

Error message

The specified source address range never had an external address pair added to the translator.

What it means

Thrown as AddressTranslationException by ExternalsAddressTranslator.getAddressRange for a single-length range whose source address is not present in addressMap. This is the range-API equivalent of the getAddress miss: the source address was never registered via setPair.

Source

Thrown at Ghidra/Features/Base/src/main/java/ghidra/app/merge/listing/ExternalsAddressTranslator.java:116

			"The specified source address set never had an external address pair added to the translator.");
	}

	@Override
	public AddressRange getAddressRange(AddressRange sourceAddressRange)
			throws AddressTranslationException {
		if (sourceAddressRange == null) {
			return null;
		}
		if (sourceAddressRange.getLength() != 1) {
			throw new AddressTranslationException(
				"An external address translator can only handle a single address at a time, if that.");
		}
		Address sourceAddress = sourceAddressRange.getMinAddress();
		Address destinationAddress = addressMap.get(sourceAddress);
		if (destinationAddress != null) {
			return new AddressRangeImpl(destinationAddress, destinationAddress);
		}
		throw new AddressTranslationException(
			"The specified source address range never had an external address pair added to the translator.");
	}

}

View on GitHub (pinned to d5f144c24d)

Solutions

Register the pair via setPair(destination, source) before calling getAddressRange.
Guard with addressMap.containsKey / use getAddress first to probe, then build the range.
Catch AddressTranslationException and fall back to a compatibility-mapping utility.

Example fix

// before
AddressRange r = translator.getAddressRange(new AddressRangeImpl(src, src)); // throws

// after — register the pair first
translator.setPair(dest, src);
AddressRange r = translator.getAddressRange(new AddressRangeImpl(src, src));

Defensive patterns

Strategy: validation

Validate before calling

Address src = sourceAddressRange.getMinAddress();
translator.setPair(map(src), src); // ensure registration before range lookup

Type guard

// ensure the source address of the single-length range was registered
boolean registered = /* wrapper exposes addressMap.containsKey(src) */;

Try / catch

try {
    return translator.getAddressRange(sourceAddressRange);
} catch (AddressTranslationException e) {
    return null; // no mapping for this external range
}

Prevention

Register all external source addresses via setPair before any range translation.
Probe with getAddress first, then wrap the result in AddressRangeImpl.

When it happens

Trigger: Calling getAddressRange on a single-length AddressRange whose min address has no registered destination — i.e. setPair was not called for that source address, or it was removed by a prior setPair(null, source).

Common situations: Translating external location ranges where only a subset of locations were pre-registered; a setPair(null, source) call inadvertently cleared a mapping.

Related errors

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