Inconsistencies in error propagation after calling _PyFrame_GetFrameObject

Bug report

Bug description:

There are 3 callers of _PyFrame_GetFrameObject which explicitly clear error when it returns NULL.

take_ownership

Lines 74 to 79 in b67a64d

    
           PyFrameObject *back = _PyFrame_GetFrameObject(prev); 
        
           if (back == NULL) { 
        
               /* Memory error here. */ 
        
               assert(PyErr_ExceptionMatches(PyExc_MemoryError)); 
        
               /* Nothing we can do about it */ 
        
               PyErr_Clear();

PyEval_GetFrame

cpython/Python/ceval.c

Lines 2562 to 2564 in b67a64d

    
           PyFrameObject *f = _PyFrame_GetFrameObject(frame); 
        
           if (f == NULL) { 
        
               PyErr_Clear();

PyThreadState_GetFrame

cpython/Python/pystate.c

Lines 2101 to 2103 in b67a64d

    
           PyFrameObject *frame = _PyFrame_GetFrameObject(f); 
        
           if (frame == NULL) { 
        
               PyErr_Clear();

PyEval_GetFrame and PyThreadState_GetFrame docs say that NULL is returned when "no frame is currently executing", and doesn't say anything about any error (probably as they explicitly clear it?).

I wonder whether PyFrame_GetBack also would want to clear error

cpython/Objects/frameobject.c

Lines 2407 to 2409 in b67a64d

    
           if (prev) { 
        
               back = _PyFrame_GetFrameObject(prev); 
        
           }

PyFrame_GetBack's documentation doesn't say anything about MemoryError which can be set by its internal API calls https://docs.python.org/3.15/c-api/frame.html#c.PyFrame_GetBack

The rest of the _PyFrame_GetFrameObject callers that don't clear error including PyFrame_GetBack are

_PyEval_ExceptionGroupMatch
_PyEval_EvalFrameDefault (error label)
_gen_getframe
sys__getframe_impl
_PyThread_CurrentFrames
_Py_call_instrumentation_line
_PyFrame_GetLocals
PyEval_GetLocals — Public C API (deprecated), no NULL check
PyFrame_GetBack — Public C API, no NULL check

And PyEval_GetLocals and PyFrame_GetBack are public C APIs that don't check for NULL and don't clear the error. I guess the internals are ok to propagate the errors?

Can someone explain whether PyFrame_GetBack not clearing error on null is ok/intended or it's a discrepancy/bug?

I would prefer PyFrame_GetBack to not propagate an error given that its documentation doesn't say anything about MemoryError.

CPython versions tested on:

CPython main branch

Operating systems tested on:

No response

Linked PRs

_PyFrame_GetFrameObject is not setting an exception (but preserves it if it exists). PyFrame_GetBack can return NULL and this is handled by frame_back_get_impl, for example. In this case frame.f_back will have None value.

From Python point of view, frame.f_back and PyFrame_GetBack can't be called with exception set.
From C-API point of view, it is responsibility of the user to handle exceptions that can exist before calling a PyFrame_GetBack.

Maybe it is worth to update a documentation that API preserves existing exceptions.

It seems that _PyFrame_GetLocals potentially can be called with frame == NULL, maybe it is worth to add checks there.

Would you like open PRs? If so please open two separate PRs, one for documentation update, one for _PyFrame_GetLocals.

I believe _gen_getframe, PyEval_GetLocals should have NULL checks or at least asserts.

sys__getframe_impl, _PyThread_CurrentFrames, _Py_call_instrumentation_line should set an exception if _PyFrame_GetFrameObject returns NULL.

_PyEval_ExceptionGroupMatch seems OK.

@markshannon

cc @markshannon as an owner
cc @colesbury as an expert

Would you like open PRs? If so please open two separate PRs, one for documentation update, one for _PyFrame_GetLocals.

Sure will do shortly

pythongh-144693: Clarify that PyFrame_GetBack preserves existing exce…

From C-API point of view, it is responsibility of the user to handle exceptions that can exist before calling a PyFrame_GetBack.

Yes, that's the general expectation for public C API functions. The behaviour is undefined if called with an active exception. If preserving the exception isn't documented, it's an implementation detail that can change in future versions.

I'm not sure if the frame experts want to turn it into a documented guarantee.

gh-144693: Clarify that `PyFrame_GetBack` does not raise exceptions (G…

pythongh-144693: Clarify that `PyFrame_GetBack` does not raise except…

[3.14] gh-144693: Clarify that `PyFrame_GetBack` does not raise excep…

[3.13] gh-144693: Clarify that `PyFrame_GetBack` does not raise excep…

pythongh-144693: Clarify that `PyFrame_GetBack` does not raise except…

Navigation Menu

Repository navigation

Inconsistencies in error propagation after calling `_PyFrame_GetFrameObject` #144693

Bug report

Bug description:

CPython versions tested on:

Operating systems tested on:

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	PyFrameObject *back = _PyFrame_GetFrameObject(prev);
	if (back == NULL) {
	/* Memory error here. */
	assert(PyErr_ExceptionMatches(PyExc_MemoryError));
	/* Nothing we can do about it */
	PyErr_Clear();

	PyFrameObject *f = _PyFrame_GetFrameObject(frame);
	if (f == NULL) {
	PyErr_Clear();

	PyFrameObject *frame = _PyFrame_GetFrameObject(f);
	if (frame == NULL) {
	PyErr_Clear();

Inconsistencies in error propagation after calling _PyFrame_GetFrameObject #144693

Description

Bug report

Bug description:

CPython versions tested on:

Operating systems tested on:

Linked PRs

Activity

sergey-miryanov commented on Feb 11, 2026

sergey-miryanov commented on Feb 11, 2026

sergey-miryanov commented on Feb 11, 2026

sergey-miryanov commented on Feb 11, 2026

taegyunkim commented on Feb 11, 2026

encukou commented on Feb 16, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Inconsistencies in error propagation after calling `_PyFrame_GetFrameObject` #144693