{"record":{"id":"da7e5f33ed4ff3ec","repo":"NationalSecurityAgency/ghidra","slug":"trace-does-not-allow-external-references","errorCode":null,"errorMessage":"Trace does not allow external references","messagePattern":"Trace does not allow external references","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/symbol/DBTraceReference.java","lineNumber":134,"sourceCode":"\t@Override\n\tpublic RefType getReferenceType() {\n\t\treturn ent.refType;\n\t}\n\n\t@Override\n\tpublic int getOperandIndex() {\n\t\treturn ent.opIndex;\n\t}\n\n\t@Override\n\tpublic SourceType getSource() {\n\t\treturn ent.getSourceType();\n\t}\n\n\t@Override\n\tpublic void setReferenceType(RefType refType) {\n\t\tif (refType == RefType.EXTERNAL_REF) {\n\t\t\tthrow new IllegalArgumentException(\"Trace does not allow external references\");\n\t\t}\n\t\ttry (LockHold hold = LockHold.lock(ent.space.lock.writeLock())) {\n\t\t\tent.setRefType(refType);\n\t\t}\n\t}\n\n\t@Override\n\tpublic void setAssociatedSymbol(Symbol symbol) {\n\t\ttry (LockHold hold = LockHold.lock(ent.space.lock.writeLock())) {\n\t\t\tAbstractDBTraceSymbol dbSym = getTrace().getSymbolManager().assertIsMine(symbol);\n\t\t\tif (ent.symbolId == symbol.getID()) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tAddress toAddress = getToAddress();\n\t\t\tif (!Objects.equals(symbol.getAddress(), toAddress)) {\n\t\t\t\tthrow new IllegalArgumentException(String.format(\n\t\t\t\t\t\"Symbol address (%s) of '%s' must match Reference's to address (%s)\",\n\t\t\t\t\tsymbol.getAddress(), symbol.getName(), toAddress));","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/symbol/DBTraceReference.java#L116-L152","documentation":"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.","triggerScenarios":"Calling ref.setReferenceType(RefType.EXTERNAL_REF) on an existing DBTraceReference. Copying a reference type set from a Program into a trace reference.","commonSituations":"Porting program-processing code that handles external refs verbatim; analyzers that enumerate all RefTypes including EXTERNAL_REF.","solutions":["Filter out RefType.EXTERNAL_REF before setting: if (refType != RefType.EXTERNAL_REF) ref.setReferenceType(refType).","Use a memory/data/flow ref type appropriate to the trace.","Model cross-program links outside the trace reference system."],"exampleFix":"// before\nref.setReferenceType(refType); // may be EXTERNAL_REF\n// after\nif (refType != RefType.EXTERNAL_REF) {\n    ref.setReferenceType(refType);\n}","handlingStrategy":"type-guard","validationCode":"if (refType != RefType.EXTERNAL_REF) {\n    ref.setReferenceType(refType);\n}","typeGuard":"static boolean isTraceAllowedRefType(RefType t) {\n    return t != RefType.EXTERNAL_REF;\n}","tryCatchPattern":null,"preventionTips":["Filter EXTERNAL_REF before setting a trace reference's type.","Do not port Program external-ref handling into traces."],"tags":["reference","external","validation"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}