Troubleshooting¶

Start with the doctor¶

apkpy doctor

This checks the JDK, Android SDK and build requirements before a long Gradle operation.

The Previewer works but Android differs¶

Run a new apkpy build; an older ZIP/project will not contain generator fixes.
Extract the new ZIP into a clean directory.
Open that new directory in Android Studio.
Let Gradle finish synchronizing.
Uninstall the old test app if application state may be stale.
Compare the generated project only after confirming it came from the current writehere.py.

Generated Java/XML files are build outputs. Fix application behavior in Python/CSS and regenerate.

A Material component crashes on open¶

The generated application must use an ApkPy-generated Material-compatible theme. Do not replace it with a legacy Theme.AppCompat theme.

If the project was manually modified, regenerate it. A MaterialCardView, MaterialToolbar or BottomNavigationView can fail during layout inflation when its Activity uses an incompatible theme.

Regenerate with the current ApkPy version. Current builds reserve space for bottom navigation. Avoid manual layout changes that move screen content outside the generated root wrapper.

A long screen is clipped¶

Use:

screen = Screen(id="screen", scroll=True)

Do not assign an unnecessary fixed height to a list inside a scrolling screen. Let content size naturally unless the list needs an intentional independent scroll area.

An async screen stays in loading¶

Hide the loading state at the first line of every success/error callback:

def loaded(success, response):
    loading.hide()
    if success:
        content.show()
    else:
        failed.show()

Also handle empty successful responses separately from failed responses.

Storage cannot decrypt an old/copy value¶

Encrypted values are device-bound. Data encrypted by Android Keystore on one installation is not intended to decrypt on another device. Treat portable data export as a separate application feature.

OAuth returns to the wrong place¶

Register apkpy://auth for Android.
Register the Previewer loopback callback shown by the flow.
Confirm the client ID belongs to the same provider configuration.
Never place a provider client secret in the APK.

Cloudflare build fails¶

Run the exact strict build locally:

python -m pip install -r requirements-docs.txt
python -m mkdocs build --strict

Then confirm Cloudflare uses:

root directory: empty;
build output directory: site;
production branch: main.

See Cloudflare Pages.