NationalSecurityAgency/ghidra · error · IllegalArgumentException

Symbol address (%s) of '%s' must match Reference's to addres

Error message

Symbol address (%s) of '%s' must match Reference's to address (%s)

What it means

Thrown as IllegalArgumentException by DBTraceReference.setAssociatedSymbol when the candidate symbol's address does not equal the reference's to-address. A reference's associated (target) symbol must live exactly at the address the reference points to, so that symbol.getAddress() == ref.getToAddress(). This keeps the reference->symbol link consistent.

Source

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

	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));
			}
			if (symbol instanceof TraceSymbolWithLifespan) {
				TraceSymbolWithLifespan symWl = (TraceSymbolWithLifespan) symbol;
				if (!symWl.getLifespan().intersects(getLifespan())) {
					throw new IllegalArgumentException(
						"Associated symbol and reference must have connected lifespans");
				}
			}
			ent.setSymbolId(symbol.getID());
			getTrace().setChanged(new TraceChangeRecord<>(TraceEvents.SYMBOL_ASSOCIATION_ADDED,
				ent.space.space, dbSym, null, this));
		}
	}

	@Override
	public void clearAssociatedSymbol() {

View on GitHub (pinned to d5f144c24d)

Solutions

1. Look up the symbol at the reference's to-address: symMgr.getSymbolAt(ref.getToAddress()).
2. Before associating, assert Objects.equals(symbol.getAddress(), ref.getToAddress()).
3. Re-resolve the symbol if it may have moved.

Example fix

// before
ref.setAssociatedSymbol(symByName);
// after
Symbol sym = symMgr.getSymbolAt(ref.getToAddress());
if (sym != null) ref.setAssociatedSymbol(sym);

if (Objects.equals(symbol.getAddress(), ref.getToAddress())) {
    ref.setAssociatedSymbol(symbol);
}

static boolean symbolMatchesRef(Symbol s, Reference r) {
    return Objects.equals(s.getAddress(), r.getToAddress());
}

When it happens

Trigger: Passing a Symbol whose address differs from the reference to-address, e.g. associating a function symbol at 0x1000 with a reference whose to-address is 0x2000.

Common situations: Lookup-by-name returning a wrong symbol at a different address; stale symbol references after a symbol moved.

Related errors

• Associated symbol and reference must have connected lifespan
• Given namespace is not part of this trace
• The given symbol is not part of this trace
• Given symbol is not part of this trace
• This symbol type cannot be a child of the given namespace ty

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