Skip to content

FAQ and Troubleshooting

Michael Riddle edited this page Jul 28, 2026 · 5 revisions

FAQ & Troubleshooting

Answers grounded in the app's actual behavior. Two halves: using the app (for singers/patrons) and building it (for contributors). If your question isn't here, check the linked page for the full story.

Using the app

Do I need an account or internet connection? What works with no signal?

No account, no login, no server — My Songs, Tonight, Singers, Venues, ratings and performance history all work fully offline. Internet is only used for a handful of optional lookups that quietly do nothing when there's no signal: auto-fill (year/genre/cover art), lyrics, the YouTube/Spotify/KaraFun quick-links, playlist import, and the update check — every one of them can be switched off in Settings. See Privacy & network.

Where does my data live? Will an app update wipe it? How do I back up or move to a new phone?

Everything is stored as JSON files in the app's private on-device storage — never synced or uploaded anywhere. Installing a new version over the old one keeps your data; only an actual uninstall wipes it. To back up or move to a new phone, go to Import & Export and export your singer profile (your songs and performance history) to a .json file, then import it on the new device. Venues export separately from the same page — they're shared across every singer on the device, not owned by one. See Import & export.

Why doesn't a song's star match the ratings I actually gave it?

The star isn't a plain average of your "how it went" scores. Settings → Singing & Ratings → "Trust a rating after" sets how many performances it takes before a song's own average is trusted over your whole list's average — until then, the star leans toward the list norm, so a single lucky 5★ won't outrank a solidly-rated ten-sing streak. Turn on Settings → Singing & Ratings → "Favour recent form" to make your most recent sings count more than old ones. See Ratings & history.

Why didn't the year, genre, or cover fill in — and why won't it try again?

Each song is looked up once: a hit or a miss both mark it "done," so a rate-limited lookup is never re-spent chasing a song that turned out to have no match. There's no "look up again" button — editing the song's title or artist is the only way to re-trigger the lookup, since that counts as a new identity to check. This is controlled by Settings → My Songs → "Enable Auto-fill Year & Genre". See Metadata & album art.

What's the ⚠ next to a song's name? Why wasn't my typo caught?

Controlled by Settings → My Songs → "Enable Song Spelling Assistant", the ⚠ means the lookup found no exact catalogue match but one result close enough to be a likely spelling slip — tap it for the "Did you mean …?" offer. It only fires when one of title/artist is spelled exactly right and the other is a small edit away — that anchor is what keeps an unrelated song, or a cover by a different artist, from being offered as a "fix." A truncated title (e.g. "Dear Maria" for "Dear Maria, Count Me In") isn't caught, because it's far more than a small edit away from the full title, so nothing is offered. See Metadata & album art.

Why is my Spotify or YouTube Music import failing?

The most common cause is a private playlist — import reads the playlist's public page, so it needs to be shareable/public first. Beyond that, the pasted link has to be a recognizable playlist link (not a link to a single track or an unrelated page). A network hiccup or the provider changing its page format shows its own specific error message rather than failing silently. See Import & export.

Where did the bottom tab bar go?

It only appears when Settings → Tabs → "Enable 'Tonight' Tab" is on. With it off, My Songs is your only destination, so the whole tab bar is hidden and navigation moves to the header ⋮ menu instead. Turn it back on to get the bar back. See Settings reference and Tonight.

I deleted a singer — are their songs gone?

Yes — immediately, with no confirmation prompt and no undo. Removing a singer deletes their My Songs and Tonight data from the device right away. (You can't delete your only singer, so there's always at least one left.) If you might want the data later, export that singer's profile from Import & Export before deleting them. See Singers.

Why isn't the venue auto-detecting?

Settings → Venues → "Enable Venue Auto-detect" only does anything once at least one saved venue has a location attached — with none, the app doesn't even ask for location permission. Add a location to a venue with "Use my current location" in its edit sheet to make auto-detect useful (scanning a venue's KaraFun QR code only sets its KaraFun catalogue link — it doesn't carry a location). If the OS denies or you decline location permission, auto-detect just quietly does nothing rather than showing an error. See Venues.

Why can't it find lyrics for a song?

Lyrics are looked up on LRCLIB by the song's title and artist exactly as entered, so a misspelled or unusually-formatted title/artist can miss a match that exists. The app tells no match apart from a match flagged instrumental, so you can see which one happened. Fixing the title/artist to how the song is commonly listed — the same fix that helps auto-fill and the ⚠ suggestion — is the usual remedy. Controlled by Settings → Song Details → "Enable 'Lyrics' Button". See Metadata & album art.

How do I replay the guided tour?

Settings → Help → "Replay the tutorial", then tap Replay — you can run it again any time.

Can other people on this device see my songs?

If they can pick up your phone, yes. Switching singers — the header avatar, or the Singers page — has no PIN or password; it's built for people casually sharing one device, not for keeping each other out. Each singer's My Songs and Tonight are kept in separate data, so switching never mixes them together, but nothing stops someone else from switching to your name and looking. See Singers.

For contributors

Failure modes worth recognizing on sight, from AGENTS.md and DEVELOPMENT.md.

Symptom Cause Fix
adb install launches then crashes: "No assemblies found in '.../.override/...'. Assuming this is part of Fast Deployment. Exiting." Debug builds use Fast Deployment — assemblies live outside the APK and are pushed separately by the MSBuild deploy target, not baked into the APK a bare adb install puts on the device. Always deploy with dotnet build … -t:Run, never a manual adb install of the Debug APK. For a self-contained APK instead, build with -p:EmbedAssembliesIntoApk=true.
Android launch crash: "No view found for id … for fragment NavigationRootManager_ElementBasedFragment" The MAUI workload's default MauiVersion (10.0.20) has a root-fragment regression on Android 16 / API 36. The csproj pins <MauiVersion>10.0.80</MauiVersion> — don't "clean it up" to the workload default. If the crash reappears after a workload update, bump to the latest serviced 10.0.x and confirm with adb logcat that the "No view found" fatal is gone.
A cold iOS build looks hung — nothing printed for minutes at actool. _CoreCompileImageAssets shells to xcrun actool to compile the asset catalog; actool is silent while it works, long enough to look dead in a foreground terminal. Redirect the build to a log and tail -f it instead of watching the terminal: dotnet build … -v:n > ios-build.log 2>&1 & then tail -f ios-build.log. Confirm actool is genuinely alive with ps -Ao pid,etime,comm | grep -iE 'actool|ibtool' — a growing etime with no crash means it's still working.
iOS build fails with ibtoold failed IDE initialization — this is a real stall, not actool silence. Xcode's extra components (used by Interface Builder tooling) were never installed via xcodebuild -runFirstLaunch. Run xcodebuild -runFirstLaunch; see the Mac Catalyst row below for the related Xcode-setup checks.
Mac Catalyst build fails with obscure Xcode-toolchain errors. Any of: xcode-select still points at Command Line Tools instead of full Xcode; the Xcode license was never accepted; xcodebuild -runFirstLaunch was never run. sudo xcode-select -s /Applications/Xcode.app/Contents/Developer; sudo xcodebuild -license accept (note xcodebuild -version succeeds without an accepted license, so it's not a valid check — read IDEXcodeVersionForAgreedToGMLicense from /Library/Preferences/com.apple.dt.Xcode instead); xcodebuild -runFirstLaunch to install the missing components (fixes the ibtoold failure above too).
A plain dotnet build on the solution surfaces iOS/Apple-toolchain errors that don't look like your code. iOS cannot be built on Windows without a paired Mac — those errors are expected, not a regression you caused. Build the Android head explicitly to verify (-f net10.0-android) on Windows; use the Windows head for fast UI iteration; validate iOS only with a Mac in the loop.
A build of one head (e.g. -f net10.0-android) fails because a workload for a TFM you didn't ask for isn't installed. MSBuild restore evaluates every declared TargetFrameworks entry even when -f narrows the build to one. dotnet workload restore src/KHost.Mobile/KHost.Mobile.csproj installs exactly the set the project declares, before building any single head.
-t:Run reports Build succeeded but nothing installs on the iOS simulator. MSBuild's deploy step can stall on the simulator even though the build itself is fine. Skip the MSBuild deploy and install the bundle directly (safe on iOS — the simulator bundle carries its own assemblies, unlike Android Fast Deployment): xcrun simctl install <udid> src/KHost.Mobile.UI/obj/_buildDebug/net10.0-ios/iossimulator-arm64/KHost.Mobile.app then xcrun simctl launch <udid> khost.mobile.
You're reviewing behavior on an emulator/simulator that turns out to be months old. Building alone doesn't install anything — an emulator/simulator keeps its last install indefinitely until a fresh -t:Run deploy. Always deploy the build you just made before looking at it, and verify the version rather than assuming: Android adb -s <serial> shell dumpsys package khost.mobile | grep versionName; iOS xcrun simctl listapps <udid> | grep -A12 khost.mobile and check CFBundleVersion (== ApplicationVersion in the csproj).
Seeding or inspecting persisted JSON on Windows doesn't show up / doesn't match. FileSystem.AppDataDirectory is the Data subfolder, not its parent — unpackaged Windows path is %LOCALAPPDATA%\KHost\khost.mobile\Data\ (the parent segments are the appxmanifest PublisherDisplayName = KHost and ApplicationId = khost.mobile). Target Data\ directly. Ignore any stale %LOCALAPPDATA%\User Name\com.companyname.khost.mobile\Data\ — that's from before the publisher/id rename and current builds don't touch it.
A newly added persisted type serializes fine in a debugger but throws (or silently no-ops) at runtime on-device. Every store uses a System.Text.Json source-generated JsonSerializerContext (SongListJsonContext, TonightJsonContext, VenueJsonContext, SingerJsonContext, LyricsCacheJsonContext, ProfileJsonContext) for trimming/AOT-safety — reflection-based serialization isn't available on the MAUI heads. Add [JsonSerializable(typeof(YourNewType))] (or make sure it's reachable from an existing root type) to the relevant context.
Album art / other JS-interop-backed features fail silently — a cover never appears, no exception thrown. The service that owns the interop must be registered scoped, not singleton: IJSRuntime is scoped in Blazor Hybrid, and a singleton captures a JS runtime that isn't attached to the live WebView, so every call to it silently fails. Register IAlbumArtService/AlbumArtService (and anything else that talks through IJSRuntime in OnAfterRenderAsync) as AddScoped, matching MauiProgram's existing registration.
UI automation on the Windows head is flaky — SendKeys drops the first burst, click coordinates drift between launches. WebView2 swallows the first SendKeys burst after launch, and page scroll position isn't stable across launches, so fixed click coordinates drift. For persistence checks, seed/read the JSON files under Data\ directly instead of driving the form. To drive the UI itself, use the playwright/ tools (CDP + real locators sidesteps both problems) — see playwright/README.md.

Other gotchas

  • adb uninstall on an emulator re-runs the first-run tutorial. Its full-screen catch-layer swallows every tap; flip settings.tutorial_completed in shared_prefs before driving the UI programmatically, or expect the tour to intercept your first clicks.
  • Fast Deployment ships assemblies, not wwwroot. If the APK is stale (e.g. an emulator restarted with -no-snapshot-save, which reverts /data including the APK) while -t:Run only pushes fresh assemblies, C# calls into JS that isn't there and the Blazor circuit dies. adb uninstall khost.mobile then redeploy clears it.
  • Back up device data before any risky redeploy or manual uninstall — a signing-key mismatch (fresh machine, regenerated debug keystore) silently forces an uninstall+reinstall that wipes all on-device singers/songs/venues/settings: dotnet run scripts/backup-device-data.cs -- backup first, … -- restore <file> to recover.

See Building & testing for full build/test commands and Architecture for project layout.

Clone this wiki locally