v3.12 Android tarball ships an unloadable libpython3.12.so after PR #5 patchelf step

[ndonkoHenri]

The python-android-mobile-forge-3.12.tar.gz asset re-uploaded after PR #5 merged ships a libpython3.12.so that Android's bionic linker refuses to load. End users' Flet apps started crashing at startup roughly the moment the new asset went live.

User-reported error (Android API ~30, real device):

[serious_python] Dart error running Python: Failed to load dynamic library 'libpython3.12.so':
dlopen failed: empty/missing DT_HASH/DT_GNU_HASH (new hash type from the future?)

Reproduced locally on a clean arm64 emulator (API 35, Pixel 9 Pro XL) — different surface message, same broken file:

$ adb shell /system/bin/linker64 /data/local/tmp/libpython3.12.so
Illegal instruction          # loader segfaults before reaching the user

# tombstone:
F DEBUG : #00 pc 0000000000000000  /data/local/tmp/libpython3.12.so

Timeline

Event	When (UTC)
commit 49d866c "android: set SONAME on libpython3.X.so via patchelf (3.12 path)"	2026-06-01T18:00
PR #5 merged to main	2026-06-01T18:33
v3.12 release asset python-android-mobile-forge-3.12.tar.gz re-uploaded	2026-06-01T18:47
Users report broken Flet apks "yesterday evening"	2026-06-01 evening CEST

The asset's updated_at matches the merge, and the breakage matches the asset upload.

Forensic evidence

Extracted install/android/arm64-v8a/python-3.12.12/lib/libpython3.12.so from the live tarball download. llvm-readelf -d shows the patchelf intervention took effect — SONAME=libpython3.12.so is now set, which is the intended outcome — but llvm-readelf -lW reveals patchelf injected a 4th PT_LOAD with 64KB alignment alongside the original 16KB-aligned segments:

Program Headers:
LOAD  off=0x000000   vaddr=0x000000  filesz=0x4915c0  R E  align=0x4000   # original
LOAD  off=0x4915c0   vaddr=0x4955c0  filesz=0x0775f8  RW   align=0x4000   # original
LOAD  off=0x508bb8   vaddr=0x510bb8  filesz=0x15a0f8  RW   align=0x4000   # original
LOAD  off=0x18a0000  vaddr=0x670000  filesz=0x009b50  RW   align=0x10000  # INJECTED by patchelf

The mismatched alignment + the new .dynstr/.dynamic indices the injected segment carries are what bionic refuses to consume. The exact error string varies by Android API level — "empty/missing DT_HASH/DT_GNU_HASH (new hash type from the future?)" on the user's device, "Illegal instruction" on my API-35 emulator — but it's the same broken artifact.

DT_GNU_HASH itself does point at valid hash data when read raw (nbuckets=433, sane bloom_size/shift), so the corruption isn't in the hash table contents directly. It's the file as a whole that the loader can't reconcile.

Likely cause

The CI runner's sudo apt-get install -y patchelf pulls Ubuntu's stock package (patchelf 0.14 on ubuntu-latest), which is known to mishandle aarch64 ELFs when relocating segments to fit a longer string in .dynstr — see NixOS/patchelf#446, #377. Newer patchelf (0.18+) ships fixes for this class of failure.

Fix options

1. Revert 49d866c and rely on replace_libpython_stub alone. Feodor's own table on PR Fix Android mobile-forge support artifact relocation #5 documents both fixes as "belt-and-suspenders", but replace_libpython_stub is the only one that's actually load-bearing for the original cannot locate symbol "PyType_IsSubtype" failure he traced — it makes consumer wheels' DT_NEEDED entries correct without touching the libpython binary itself. This is the safest unblock.

2. Pin a newer patchelf in the workflow (pip install patchelf==0.18.0 exposes a maintained wheel; or grab the official aarch64 binary from the patchelf release page) before running the --set-soname step.

3. Skip patchelf and use the linker directly at libpython build time — add -Wl,-soname,libpython3.X.so via a Makefile override so the SONAME is set during CPython's link step, not retroactively. This is what 3.13+ does natively.

Option 1 is the fastest path to a fixed v3.12 tarball. Option 3 is the cleanest long-term.

What end users need

Nothing client-side fixes this — the broken .so is fetched by every flet build apk until the v3.12 asset is replaced. Once the asset is re-published with a working libpython3.12.so, the user's next flet build apk produces a working APK with no app-side change.

[ndonkoHenri]

Follow-up on PR #5: the patchelf SONAME step is corrupting libpython3.12.so

Reposting some end-to-end findings here in one place — bug mechanism, options we considered, and empirical results for each — so the rationale for the PR following this comment is on the record.

TL;DR

The patchelf --set-soname step we added in #5 produces a libpython3.12.so that crashes Python init on permissive Android bionic (silent blank screen) and fails dlopen outright on stricter bionic (the empty/missing DT_HASH/DT_GNU_HASH (new hash type from the future?) error multiple users have reported). The bug is not patchelf per se — it's the interaction with llvm-strip later in the pipeline. There are three viable fix shapes; I implemented all three, validated each end-to-end on emulator against a fresh CI build, and the linked PR ships the cleanest of them.

What is actually broken in main

Today's pipeline is:

1. android/build.sh — make install → patchelf --set-soname libpython3.12.so on the install-tree libpython.
2. android/package-for-dart.sh (later) — llvm-strip every .so, including that same libpython, when packaging the dart tarball.

patchelf --set-soname doesn't just write a string. It relocates
.dynstr / .dynamic into a brand new PT_LOAD segment appended to the
end of the file. At insertion time this segment is correctly placed:

LOAD  off=0x18a0000  va=0x670000  align=0x10000   →   off % 0x10000 == va % 0x10000 == 0   ✓

The ELF spec requires p_offset ≡ p_vaddr (mod p_align) for every PT_LOAD so that the loader can mmap from a page-aligned file offset and land the bytes at the right virtual address.

Then llvm-strip from NDK r27d (the one we're pinned to via android/android-env.sh) removes about 54 KB more bytes than the LLVM version on newer NDKs strip, which shifts every following file offset down. p_vaddr stays at 0x670000 (vaddrs are stable across strip), but p_offset becomes 0x662cb0:

LOAD  off=0x662cb0   va=0x670000   align=0x10000   →   off % 0x10000 = 0x2cb0   va % 0x10000 = 0x0   ❌

That's the spec violation. At dlopen, bionic page-aligns p_offset down and maps from a wrong starting offset. The virtual address where PT_DYNAMIC says .dynamic lives (va = 0x6799c0) now resolves to a file offset inside .dynstr instead of into .dynamic proper.

I verified the byte arithmetic by hand. With 4 KB pages, bionic reads the "dynamic section" from file offset 0x66b9c0:

$ python3 -c "open('libpython3.12.so','rb').seek(0x66b9c0); print(open('libpython3.12.so','rb').read(48))"
b'races\x00_PyTraceMalloc_GetObjectTraceback\x00_PyTrace'

Those are Python symbol names from .dynstr — being interpreted as Elf64_Dyn structs by the loader. The bionic linker log on emulator-5554 (Pixel API 29) shows it iterating over these as unknown DT entries:

W linker  : Warning: "/.../libpython3.12.so" unused DT entry: unknown
            (type 0x505f007365636172 arg 0x614d656361725479) (ignoring)

Decode the type/arg fields as 8-byte little-endian: b'races\x00_P', b'yTraceMa'. Same bytes I found on disk. Twenty-five of those warnings per dlopen, two dlopen calls (once at JNI library load, once when serious_python's Dart code explicitly opens it). On API 29 bionic logs the warnings and continues; on stricter bionic builds the loader rejects the file outright with the empty/missing DT_HASH/DT_GNU_HASH message users are reporting, because the iteration walks past where the real DT_GNU_HASH entry should be without finding it.

Even on the permissive bionic case where dlopen "succeeds with warnings", the wrong .dynamic contents mean later C-API calls into Python use bogus pointers and Py_Initialize silently crashes. Visible symptom: blank screen.

Why the fix in 3.13 isn't needed

CPython 3.13's official Android tooling passes -Wl,-soname during the actual libpython link, so ld stamps DT_SONAME directly into the ELF. No patchelf, no injected PT_LOAD, no alignment to break. I verified the v3.13 release tarball ships a clean 3-LOAD ELF with SONAME = libpython3.13.so set natively.

CPython 3.12 has the same -Wl,-h$(INSTSONAME) logic in Makefile.pre.in but only enables it when INSTSONAME != LDLIBRARY, and our soname patch already makes them equal on Android — so the else branch runs and ld is called without -Wl,-soname.
That's the root cause we should fix.

Options considered

I built and tested three fix shapes end-to-end. Each was on its own branch off main, built via CI with workflow_dispatch, and the resulting python-android-dart-3.12-arm64-v8a.tar.gz was dropped into a minimal Flet app (playground/build-tester) via SERIOUS_PYTHON_DART_TARBALL_DIR and run on emulator-5554 (Pixel API 29, arm64-v8a).

A — Set SONAME at link time (drop patchelf entirely)

Branch: soname-A-makefile-linktime.

• Add android/patches/soname_linktime.patch (one-line Makefile.pre.in edit: add -Wl,-h$(INSTSONAME) to the else branch of the libpython link rule).
• Remove the patchelf --set-soname block from android/build.sh.
• Remove the apt-get install -y patchelf step from .github/workflows/build-python-version.yml.

ld stamps DT_SONAME natively during the libpython link. No post-process, no injected PT_LOAD, no exposure to whichever llvm-strip happens to be in NDK toolchain we use. This is the same shape of fix 3.13 already ships.

B — Strip before patchelf (reorder)

Branch: soname-B-strip-then-patchelf.

• In android/build.sh, run "$STRIP" on $PREFIX/lib/libpython3.X.so immediately before patchelf --set-soname.
• Add a guard in android/package-for-dart.sh's strip loop to skip libpython*.so (it's already stripped at this point).

Keeps patchelf as a load-bearing tool but stops llvm-strip from ever running on a patchelf-mutated file. The injected PT_LOAD lands at an offset that no later step shifts. Smallest behavioral diff from the current pipeline; smallest CPython-source diff (zero).

C — Re-patchelf after strip with name-bounce

Branch: soname-C-patchelf-after-strip.

• Keep build.sh unchanged.
• In package-for-dart.sh after llvm-strip, run a two-call patchelf bounce: set SONAME to a placeholder, then set it back. Idea: the longer placeholder forces patchelf to extend .dynstr and append a fresh aligned PT_LOAD, and PT_DYNAMIC gets pointed at the new segment.

Conceptually minimal — touches only package-for-dart.sh. Empirically broken (see below).

Empirical results

All three branches were built via workflow_dispatch (auto-push CI on the fork startup-fails for unrelated reasons — separate issue). I pulled each python-android-dart-3.12-arm64-v8a.tar.gz, extracted libpython3.12.so, and inspected its program headers and dynamic section. Then I built the same Flet app against each tarball, installed on emulator-5554, captured logcat for linker warnings and serious_python lifecycle markers, and screenshotted the launched app. The emulator state was reset between options.

	PT_LOAD count	Alignment	DT_SONAME	Linker warnings on dlopen	[serious_python] CPython loaded	[serious_python] after Py_Initialize()	UI renders
Broken baseline (main HEAD)	4	❌ misaligned LOAD	✓	25 × 2	✗	✗	blank
Clean baseline (HEAD~ before patchelf step)	3	✓	✗	0	✓	✓	renders (but wheels' DT_NEEDED would be wrong)
A — Makefile linktime	3	✓	✓	0	✓	✓	renders
B — strip-then-patchelf	4	✓	✓	0	✓	✓	renders
C — bounce-rename	5	❌ old broken LOAD still present	✓	4	✗	✗	blank

A and B both fix the runtime bug. C does not.

Why C failed

Static analysis after the fact: patchelf's bounce did append a fresh aligned PT_LOAD for the extended .dynstr + .dynsym, but it did not move .dynamic itself. PT_DYNAMIC.p_vaddr still resolves to 0x6799c0, which is inside the original llvm-strip-broken PT_LOAD segment. Bionic still mis-mmaps that segment, still reads .dynstr bytes as .dynamic entries — same root cause as the unmitigated bug, just with fewer warnings (because some of the misread addresses now point into the new aligned segment where they happen to match real data). The "old broken segment is dead weight" assumption was wrong: it's the segment PT_DYNAMIC points at, so it's the one bionic actually consults.

Why I'd land A rather than B

Both work. The argument for A:

• It deletes the failure mode rather than working around it. No patchelf in the build means no future risk of an upstream llvm-strip / patchelf / NDK upgrade re-introducing the same shape of bug under different specific offsets. B keeps patchelf, just orders things carefully — that ordering is now load-bearing and needs to be preserved by anyone touching either script.
• It matches what 3.13+ already does, so the 3.12 build path stops being a special snowflake.
• It drops a CI dependency (the apt-get install patchelf step).
• The patch is one substantive line (add -Wl,-h$(INSTSONAME) to the else branch of the existing libpython link rule). It dry-run applies cleanly to python/cpython@v3.12.12's Makefile.pre.in. The rule it touches hasn't changed across recent 3.12.x point releases.

PR with branch A follows.