NationalSecurityAgency/ghidra · error · IllegalArgumentException

Trace does not allow external references

Error message

Trace does not allow external references

What it means

Thrown as IllegalArgumentException by DBTraceReference.setReferenceType when the requested type is RefType.EXTERNAL_REF. Trace references model intra-trace references only; external (library) references that Ghidra's flat-program model supports are deliberately not permitted on traces, because traces have no external-program linkage concept.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/symbol/DBTraceReference.java:134

	@Override
	public RefType getReferenceType() {
		return ent.refType;
	}

	@Override
	public int getOperandIndex() {
		return ent.opIndex;
	}

	@Override
	public SourceType getSource() {
		return ent.getSourceType();
	}

	@Override
	public void setReferenceType(RefType refType) {
		if (refType == RefType.EXTERNAL_REF) {
			throw new IllegalArgumentException("Trace does not allow external references");
		}
		try (LockHold hold = LockHold.lock(ent.space.lock.writeLock())) {
			ent.setRefType(refType);
		}
	}

	@Override
	public void setAssociatedSymbol(Symbol symbol) {
		try (LockHold hold = LockHold.lock(ent.space.lock.writeLock())) {
			AbstractDBTraceSymbol dbSym = getTrace().getSymbolManager().assertIsMine(symbol);
			if (ent.symbolId == symbol.getID()) {
				return;
			}
			Address toAddress = getToAddress();
			if (!Objects.equals(symbol.getAddress(), toAddress)) {
				throw new IllegalArgumentException(String.format(
					"Symbol address (%s) of '%s' must match Reference's to address (%s)",
					symbol.getAddress(), symbol.getName(), toAddress));

View on GitHub (pinned to d5f144c24d)

Solutions

1. Filter out RefType.EXTERNAL_REF before setting: if (refType != RefType.EXTERNAL_REF) ref.setReferenceType(refType).
2. Use a memory/data/flow ref type appropriate to the trace.
3. Model cross-program links outside the trace reference system.

Example fix

// before
ref.setReferenceType(refType); // may be EXTERNAL_REF
// after
if (refType != RefType.EXTERNAL_REF) {
    ref.setReferenceType(refType);
}

if (refType != RefType.EXTERNAL_REF) {
    ref.setReferenceType(refType);
}

static boolean isTraceAllowedRefType(RefType t) {
    return t != RefType.EXTERNAL_REF;
}

When it happens

Trigger: Calling ref.setReferenceType(RefType.EXTERNAL_REF) on an existing DBTraceReference. Copying a reference type set from a Program into a trace reference.

Common situations: Porting program-processing code that handles external refs verbatim; analyzers that enumerate all RefTypes including EXTERNAL_REF.

Related errors

• Symbol address (%s) of '%s' must match Reference's to addres
• Associated symbol and reference must have connected lifespan
• Given reference is not in this trace
• Invalid number of elements specified: {}
• pos cannot be less than zero

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