What causes "PYTHONDUMPREFSFILE: cannot create file: %ls\n" in python/cpython?

mkdir -p the target directory and ensure the user can write it

PYTHONDUMPREFSFILE: cannot create file: %ls\n

Error message

PYTHONDUMPREFSFILE: cannot create file: %ls\n

What it means

Printed in Py_Finalize (Python/pylifecycle.c, Py_TRACE_REFS builds only) when PYTHONDUMPREFSFILE names a file that _Py_wfopen cannot open for writing. Reference dumping to that file is skipped (dump_refs_fp stays NULL); if PYTHONDUMPREFS is also set, output still goes to stderr. Exit continues normally.

Source

Thrown at Python/pylifecycle.c:2547

    /* unload faulthandler module */
    _PyFaulthandler_Fini();

    /* dump hash stats */
    _PyHash_Fini();

#ifdef Py_TRACE_REFS
    /* Display all objects still alive -- this can invoke arbitrary
     * __repr__ overrides, so requires a mostly-intact interpreter.
     * Alas, a lot of stuff may still be alive now that will be cleaned
     * up later.
     */

    FILE *dump_refs_fp = NULL;
    if (dump_refs_file != NULL) {
        dump_refs_fp = _Py_wfopen(dump_refs_file, L"w");
        if (dump_refs_fp == NULL) {
            fprintf(stderr, "PYTHONDUMPREFSFILE: cannot create file: %ls\n", dump_refs_file);
        }
    }

    if (dump_refs) {
        _Py_PrintReferences(tstate->interp, stderr);
    }

    if (dump_refs_fp != NULL) {
        _Py_PrintReferences(tstate->interp, dump_refs_fp);
    }
#endif /* Py_TRACE_REFS */

    /* At this point there's almost no other Python code that will run,
       nor interpreter state needed.  The only possibility is the
       finalizers of the objects stored on tstate (and tstate->interp),
       which are triggered via finalize_interp_clear().

       For now we operate as though none of those finalizers actually

View on GitHub (pinned to bc6749cc3b)

Solutions

mkdir -p the target directory and ensure the user can write it
Use an absolute path in a writable location, e.g. PYTHONDUMPREFSFILE=/tmp/refs.txt
Verify you are on a --with-trace-refs build (python -c 'import sys; print(sys.gettotalrefcount())' works only there)

Example fix

# before
PYTHONDUMPREFSFILE=/nonexistent/dir/refs.txt ./python-dbg app.py
# after
mkdir -p /tmp/refs && PYTHONDUMPREFSFILE=/tmp/refs/refs.txt ./python-dbg app.py

Defensive patterns

Strategy: validation

Validate before calling

# bash: pre-create and check writability before the run
D=$(dirname "$PYTHONDUMPREFSFILE"); mkdir -p "$D" && touch "$PYTHONDUMPREFSFILE" || exit 1
PYTHONDUMPREFSFILE="$PYTHONDUMPREFSFILE" ./python-dbg app.py

Prevention

Always mkdir -p the dump directory in leak-hunting scripts
Use absolute, writable paths like /tmp for PYTHONDUMPREFSFILE in CI
Remember this only exists on --with-trace-refs builds; regular builds ignore the variable silently

When it happens

Trigger: Running a --with-trace-refs debug build with PYTHONDUMPREFSFILE set to a path in a nonexistent directory, a path without write permission, or an unwritable name; the fopen("w") fails.

Common situations: Debug builds used for reference-leak hunting where the output path was never created; CI running as a user without write access to the target dir; typo'd filenames.

Related errors

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/0de65b9090215c46. Report an issue: GitHub.