PyO3/pyo3 · error

cannot fail due to mask

Error message

cannot fail due to mask

What it means

PyVectorcall_NARGS masks off the PY_VECTORCALL_ARGUMENTS_OFFSET flag bit from a vectorcall nargsf value and converts the result to Py_ssize_t. Since the mask guarantees the value fits in Py_ssize_t (the flag is the top bit and the remainder fits ssize_t), the try_into cannot fail; the expect is an internal invariant assertion.

Source

Thrown at pyo3-ffi/src/cpython/abstract_.rs:56

        callable: *mut PyObject,
        args: *const *mut PyObject,
        nargs: Py_ssize_t,
        keywords: *mut PyObject,
    ) -> *mut PyObject;
}

#[cfg(not(Py_3_12))]
const PY_VECTORCALL_ARGUMENTS_OFFSET: size_t = (1 as size_t)
    .checked_shl((8 * core::mem::size_of::<size_t>() - 1) as u32)
    .expect("size_t should fit the flag bits");

#[cfg(Py_3_12)] // public API from 3.12
use crate::PY_VECTORCALL_ARGUMENTS_OFFSET;

#[inline(always)]
pub unsafe fn PyVectorcall_NARGS(n: size_t) -> Py_ssize_t {
    let n = n & !PY_VECTORCALL_ARGUMENTS_OFFSET;
    n.try_into().expect("cannot fail due to mask")
}

#[cfg(any(PyPy, Py_3_11))]
extern_libpython! {
    #[cfg_attr(PyPy, link_name = "PyPyVectorcall_Function")]
    pub fn PyVectorcall_Function(callable: *mut PyObject) -> Option<vectorcallfunc>;
}

#[cfg(not(any(PyPy, Py_3_11)))]
#[inline(always)]
pub unsafe fn PyVectorcall_Function(callable: *mut PyObject) -> Option<vectorcallfunc> {
    assert!(!callable.is_null());
    let tp = crate::Py_TYPE(callable);
    if PyType_HasFeature(tp, Py_TPFLAGS_HAVE_VECTORCALL) == 0 {
        return None;
    }
    assert!(PyCallable_Check(callable) > 0);
    let offset = (*tp).tp_vectorcall_offset;

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Ensure the size_t value passed in is a genuine nargsf from a vectorcall, not arbitrary data
2. Use a supported platform/toolchain
3. Audit FFI boundaries for corrupted argument values

// validate nargsf looks like a vectorcall count before passing on
fn valid_nargsf(n: usize) -> bool { n & !PY_VECTORCALL_ARGUMENTS_OFFSET <= isize::MAX as usize }

When it happens

Trigger: Practically unreachable: it would require a size_t/Py_ssize_t width relationship where a masked vectorcall argument count doesn't fit Py_ssize_t — not possible on supported CPython builds.

Common situations: Seen in panic backtraces only if a FFI caller passes a corrupted nargsf on a hypothetical platform with mismatched size_t/ssize_t widths.

Related errors

• size_t should fit the flag bits
• size_t should fit the flag bits
• frozenset should always be iterable
• Neither abi3 or abi3t features are enabled
• Cannot target an abi3t version below {MINIMUM_SUPPORTED_VERS

AI-assisted analysis of PyO3/pyo3@ac9b6899d3 (2026-09-05). Data as JSON: /api/errors/788392e4ce870197. Report an issue: GitHub.