Troubleshooting

Troubleshooting

The questions that actually come up. If your problem isn't here, file an issue — chances are someone else hit the same thing.

Sideload install

"Install blocked" or "For your security…"

Android won't install APKs from unknown sources by default. Per-app permission flow:

1. Open the file manager or browser you used to download the APK.
2. Tap the APK once. Android shows the "Install blocked" dialog with a Settings button.
3. Tap Settings, toggle Allow from this source for that specific browser/file manager.
4. Go back, tap the APK again, install.

You only do this once per source app.

"App not installed as package conflicts with an existing package"

Two cases to know:

1. Pre-v0.4.15 debug build → v0.4.15+ build. The signing fingerprint changed when we checked in a stable debug keystore (#15). Uninstall the old debug build once, then install the new one. Library, voices, and progress are not preserved across this one-time migration.
2. Release build → debug build (or vice versa). Different signing certificates. Uninstall the other one first.

From v0.4.15 onward, debug-to-debug upgrades and release-to-release upgrades work in place.

"Parse error" on install

The APK download was incomplete or corrupted. Re-download from the Releases page — verify the file size matches the GitHub asset size before opening.

First-launch voice picker

The voice download spinner sticks forever

Voices download from voices-v2 on jphein/VoxSherpa-TTS. Two things to check:

1. Network. First-launch voice download requires Wi-Fi by default. Toggle off Settings → Library & Sync → Wi-Fi only if you want to download on cellular.
2. Available storage. Piper voices are 14–30 MB; Kokoro is ~330 MB. If your device is near full, the install fails silently. Free 500+ MB and retry.

If it still hangs, Settings → Voice library → long-press the voice → Delete partial and retry the download.

"Voice download failed: HTTP 404"

You're probably on an outdated app build whose VoiceCatalog.kt references voices that have been replaced or removed in voices-v2. Update to the latest release — the catalog is compiled into the APK, so app updates pick up catalog changes.

Playback

Synthesis falls behind on long sentences

Symptoms: the audio pauses mid-chapter, refills, resumes. The PCM cache is doing its job — the engine couldn't keep up, so it's buffering ahead. To minimize this:

• Settings → Performance → Engines / Threads. Bump engines from 1 → 2 (or higher if you have 4+ cores). Each engine adds memory pressure (~50 MB for Kokoro), so don't go higher than your device's RAM allows.
• Settings → Performance → Buffer chunks. Higher = more headroom before underrun, more delay before playback starts. The slider takes effect mid-listen.
• Use a Piper voice instead of Kokoro on slow hardware. Kokoro is higher quality but ~3× slower per chunk. Piper-medium is the sweet spot on Helio P22T-class chips.

Audio is fuzzy / distorted

If you've been on storyvox since v0.4.x and never re-downloaded voices, the old voices-v1 INT8-quantized models may still be on disk. Settings → Voice library → long-press → Delete, then re-download — the app pulls fp32 weights from voices-v2.

Playback stops when I lock the screen

Settings → Account → Storyvox notification permission must be granted. The lock-screen tile is what keeps the playback service foregrounded; without the notification permission, Android kills the service when the screen locks.

"Resume" auto-played at me when I just wanted to read

Update to v0.4.83+. The Library Resume CTA is now smart-resume — it respects your last paused/playing intent so it won't auto-play unless you were playing when you last left.

Azure HD voices (BYOK)

"Test connection" fails

In Settings → Voice & Playback → Azure, the most common causes:

1. Region mismatch. The region must match exactly what's in the Azure portal (e.g. eastus, not East US; westeurope, not West Europe).
2. Key has expired or been rotated. Pull a fresh key from the Azure portal.
3. Network blocked. Azure Speech requires HTTPS to <region>.tts.speech.microsoft.com. Some captive Wi-Fi blocks this — try mobile data.

"Azure voice fell back to local"

Expected behavior — when Azure errors mid-chapter, storyvox falls back to your selected local voice for the rest of the chapter so playback doesn't stop. Watch for transient HTTP 429 (rate limit) or 5xx errors; the engine retries before falling back. If it falls back every chapter, your subscription tier may not support the voice you picked (Dragon HD is on a separate tier from HD Neural).

My Azure bill is higher than expected

storyvox shows a per-chapter cost estimate before each Azure-narrated chapter starts (under the play button). The figure uses the VoiceCost.centsPer1MChars = 3000 constant in VoiceCatalog.kt, which is Azure's standard rate as of late 2025. If Azure has raised pricing on your tier, that constant will lag — file an issue and we'll bump it. The actual bill is whatever Azure charges; storyvox doesn't see your billing.

GitHub OAuth (Device Flow)

The Device Flow code expires before I can paste it

Codes from https://github.com/login/device are valid for 15 minutes. If you exceed that, hit Cancel → Try again in the storyvox sign-in flow to get a fresh code.

"Insufficient scope" when accessing private repos

Private-repo access is opt-in. Settings → Library & Sync → GitHub → Allow private repos must be on, AND your initial OAuth grant has to include the repo scope. If you opted out of private repos at first sign-in, sign out and back in — storyvox will re-request consent with the wider scope.

"My Repos" is empty after signing in

Two checks:

1. Hit pull-to-refresh on the My Repos tab. The list lazy-loads on first open.
2. Check Settings → Library & Sync → GitHub → Status for the rate-limit indicator. Authenticated requests have 5,000/hr — you should never hit this casually, but a runaway poll bug could.

Browse infinite scroll

Scrolling stops loading new fictions

Royal Road, GitHub Search, RSS, Outline, and MemPalace tabs all use infinite scroll. If new pages stop loading:

1. Network. Check connection. The "no more results" sentinel and a network error look the same in the UI. (We're working on better differentiation in the next polish round.)
2. End of source. Some sources don't have infinite results — the curated GitHub registry is a finite list, your follows tab is bounded by your follow count, etc.
3. Filter too narrow. Royal Road's filter sheet supports tag exclude / content-warning combos that can produce empty pages — try a broader filter.

EPUB / RSS / Outline / MemPalace setup

"No EPUB folder selected"

Settings → Library & Sync → EPUB prompts for a folder via the Storage Access Framework. Pick a folder that contains .epub files (not the EPUBs themselves — a folder of them). Storyvox parses each EPUB's .opf manifest to extract chapters.

RSS feed shows up but plays the same chapter every time

This was a real bug (fix in 7904232). Update to v0.4.71 or newer — the chapter routing was being short-circuited on duplicate-keyed feed items.

Outline collection 404s

Outline self-hosts; storyvox needs your Outline server's URL + an API token from your Outline user settings. Settings → Library & Sync → Outline → URL must include the protocol (https://outline.example.com).

MemPalace shows "Daemon offline"

MemPalace is LAN-only by design. Storyvox connects to your palace daemon's HTTP API; both phone and palace must be on the same network. If the daemon is reachable from a desktop browser but not from storyvox, check Settings → Library & Sync → Memory Palace → Daemon URL — it has to be the IP your phone can reach (often http://<host>.local:<port> or http://10.x.x.x:<port>).

Wear OS

Wear app pairs but transport controls don't work

Wear OS support is experimental. The :wear module builds and pairs via play-services-wearable, but transport-state syncing is rough. Sideload at your own risk; expect to fall back to the phone for now.

Anything else

If your problem isn't here:

1. Search open issues.
2. Search closed issues — most users' problems are reproductions of something we already fixed.
3. File a new one with: device model, Android version, app version (Settings → About), and what you did right before the problem.