NationalSecurityAgency/ghidra · error · UnwindException

The program counter reference is missing for the frame!

Error message

The program counter reference is missing for the frame!

What it means

ListingUnwoundFrame.loadProgramCounter() scans references TO the frame's address looking for a DATA reference at operand index StackUnwinder.PC_OP_INDEX, which records the program counter. If no such reference is found, the frame annotation is incomplete and it throws UnwindException("The program counter reference is missing for the frame!"). The PC reference is the anchor that lets the listing-based unwinder locate the frame in static space.

Source

Thrown at Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/ListingUnwoundFrame.java:184

	private int loadLevel() {
		Integer l = getLevel(frame);
		if (l == null) {
			throw new IllegalStateException("Frame has no comment indicating its level");
		}
		return l;
	}

	private Address loadProgramCounter() {
		for (Reference ref : frame.getReferenceIteratorTo()) {
			if (ref.getReferenceType() != RefType.DATA) {
				continue;
			}
			if (ref.getOperandIndex() != StackUnwinder.PC_OP_INDEX) {
				continue;
			}
			return ref.getFromAddress();
		}
		throw new UnwindException("The program counter reference is missing for the frame!");
	}

	private Address mapProgramCounter() {
		ProgramLocation location = mappingService.getOpenMappedLocation(
			new DefaultTraceLocation(trace, null, Lifespan.at(snap), pcVal));
		if (location.getProgram() != function.getProgram()) {
			return null;
		}
		return location.getByteAddress();
	}

	private Function loadFunction() {
		ProgramLocation staticLoc =
			mappingService.getOpenMappedLocation(new DefaultTraceLocation(frame.getTrace(), null,
				Lifespan.at(coordinates.getSnap()), pcVal));
		if (staticLoc == null) {
			throw new UnwindException(
				"The program containing the frame's function is unavailable," +

View on GitHub (pinned to d5f144c24d)

Solutions

1. Ensure frame annotations are created through the stack unwinder so the PC reference (DATA ref at PC_OP_INDEX) is written.
2. Re-create/re-annotate the frame so the PC reference is restored.
3. Catch UnwindException and skip the malformed frame, reporting it for repair.

Example fix

// before
Address pc = frame.loadProgramCounter(); // throws: PC reference missing

// after
try {
    Address pc = frame.loadProgramCounter();
} catch (UnwindException e) {
    Msg.warn(this, "Frame lacks PC reference; re-annotate the stack frame");
    return null;
}

// Pre-check that the frame annotation has the PC DATA reference
boolean hasPc = false;
for (Reference ref : frame.getReferenceIteratorTo()) {
    if (ref.getReferenceType() == RefType.DATA
            && ref.getOperandIndex() == StackUnwinder.PC_OP_INDEX) {
        hasPc = true; break;
    }
}
if (!hasPc) {
    // re-annotate the frame via the stack unwinder before loading
}

public static boolean frameHasPcReference(ghidra.program.model.listing.CodeUnit frame) {
    for (Reference ref : frame.getReferenceIteratorTo()) {
        if (ref.getReferenceType() == RefType.DATA
                && ref.getOperandIndex() == StackUnwinder.PC_OP_INDEX) {
            return true;
        }
    }
    return false;
}

try {
    Address pc = frame.loadProgramCounter();
} catch (UnwindException e) {
    if (e.getMessage().contains("program counter reference is missing")) {
        // re-create the frame annotation via the stack unwinder, then retry
    } else throw e;
}

When it happens

Trigger: Loading a stack frame annotation that was created without (or stripped of) its PC operand reference. Manually constructed/corrupt frame bookmarks that lack the DATA ref at PC_OP_INDEX. Frames whose PC reference was deleted by the user or another plugin.

Common situations: Older or hand-edited frame annotations missing the PC reference. Plugins/tools that create frame annotations incompletely. Reference cleanup operations that removed the PC DATA ref.

Related errors

• Cannot map %s:%s to dynamic adress
• Return address must be in {}
• Cannot compute stack address for offset %d.\nFrame error: %s
• Return address must be in {}
• The program containing the frame's function is unavailable,

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