NationalSecurityAgency/ghidra · error · UnknownContextException

Trace does not contain referenced instruction: ({getStartSna

Error message

Trace does not contain referenced instruction: ({getStartSnap},{instructionAddress})

What it means

Thrown by DBTraceInstruction.getParserContext(Address instructionAddress) when the caller requests a parser context at an address different from this instruction's own address, and the trace's instruction manager has no instruction at (getStartSnap(), instructionAddress). This is an UnknownContextException (checked), indicating the referenced instruction does not exist in the trace at the given snap and address. The method first checks if instructionAddress equals this instruction's address (returning its own context); otherwise it performs a lookup that returned null.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/DBTraceInstruction.java:865

	public ParserContext getParserContext() throws MemoryAccessException {
		return parserContext == null
				? parserContext = prototype.getParserContext(getMemBuffer(), getProcessorContext())
				: parserContext;
	}

	@Override
	public ParserContext getParserContext(Address instructionAddress)
			throws UnknownContextException, MemoryAccessException {
		// TODO: Why is this a method of Instruction? Seems should be of Listing.
		// NOTE: Taken from InstructionDB#getParserContext(Address) 
		// Admittedly, I don't understand what it's for
		if (getAddress().equals(instructionAddress)) {
			return getParserContext();
		}
		DBTraceInstruction instruction =
			space.manager.instructions.getAt(getStartSnap(), instructionAddress);
		if (instruction == null) {
			throw new UnknownContextException("Trace does not contain referenced instruction: (" +
				getStartSnap() + "," + instructionAddress + ")");
		}
		// Ensure that prototype is the same implementation
		InstructionPrototype otherProto = instruction.getPrototype();
		if (!otherProto.getClass().equals(prototype.getClass())) {
			throw new UnknownContextException("Instruction has incompatible prototype at: (" +
				getStartSnap() + "," + instructionAddress + ")");
		}
		return instruction.getParserContext();
	}
}

View on GitHub (pinned to d5f144c24d)

Solutions

Verify the instruction exists at the referenced address before calling getParserContext by checking space.manager.instructions.getAt(snap, address) is non-null.
Pass the instruction's own address (getAddress()) to get its own parser context instead of a foreign address.
Catch UnknownContextException and handle the missing instruction gracefully (skip, log, or disassemble the target first).

Example fix

// before
ParserContext ctx = instruction.getParserContext(targetAddress);

// after
DBTraceInstruction target =
    space.manager.instructions.getAt(instruction.getStartSnap(), targetAddress);
ParserContext ctx = (target != null)
    ? instruction.getParserContext(targetAddress)
    : instruction.getParserContext(); // fall back to own context

Defensive patterns

Strategy: validation

Validate before calling

// Check the target instruction exists before requesting its parser context
Address targetAddr = /* the referenced address */;
if (instruction.getAddress().equals(targetAddr)) {
    // safe — own context
} else {
    DBTraceInstruction target = space.manager.instructions
        .getAt(instruction.getStartSnap(), targetAddr);
    if (target == null) {
        // no instruction at target; do not call getParserContext(targetAddr)
    }
}

Try / catch

try {
    ParserContext ctx = instruction.getParserContext(targetAddress);
} catch (UnknownContextException e) {
    // no instruction at the referenced address in this trace/snap
    // fall back to own context or disassemble target first
}

Prevention

Verify instruction existence at referenced addresses before calling getParserContext.
Use getParserContext() with no args when you need the instruction's own context.
Ensure all flow targets are disassembled before cross-referencing parser contexts.

When it happens

Trigger: Calling getParserContext(someOtherAddress) on a DBTraceInstruction where someOtherAddress is not the instruction's own address, and no DBTraceInstruction exists in space.manager.instructions at (getStartSnap(), someOtherAddress). This happens when the caller passes an address from a flow target that has not yet been disassembled or recorded in the trace.

Common situations: During cross-instruction context resolution when following flow (branch targets) that were never disassembled. When a trace was loaded that is missing instructions at referenced addresses. When the snap referenced by the instruction does not have the target instruction recorded.

Related errors

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