← All troubleshooting topics

App lock

The app lock is a hard gate. Forgotten credentials can’t be recovered inside the app, and several destructive commands ask for them again even after you’ve unlocked.

I forgot my PIN or password

You can’t unlock the app.

There is no recovery path inside the app. The lock is an Argon2id hash in your OS credential store; Loach cannot read or reverse it, and the in-app Factory reset asks for the credentials too. Your options are:

• Try the optional hint - click Show hint on the lock screen (it only appears if you set one).
• Remove the lock’s entry from the credential store by hand. Loach stores it under the service dev.loach.app with the account app_lock:
  • Windows: open Credential Manager → Windows Credentials and, under Generic Credentials, remove the entry whose name contains app_lock and dev.loach.app.
  • Linux: delete it in your keyring app (Passwords and Keys, KWalletManager), or run secret-tool clear service dev.loach.app username app_lock.
  • macOS: in Keychain Access, delete the dev.loach.app item whose account is app_lock.
  Your chats and settings are untouched - only the lock is gone. Loach also remembers that a lock was set in a small marker file, app_lock.json, next to its database in the app-data folder, so the next launch still shows the lock screen once: enter anything - any PIN of the right length, any password - to get in, and it starts unlocked from then on. Delete app_lock.json as well to skip that last lock screen.

Deleting the app-data folder does not help: it wipes your chats but leaves the credential-store entry, so the lock screen comes straight back.

Set a hint when you create a lock - it’s stored alongside in plain text for exactly this case.

“Too many failed attempts” on the lock screen

After several wrong PINs, every unlock attempt is refused with Too many failed attempts. Try again in N seconds.

After 5 consecutive failed attempts, Loach starts an escalating cool-down (30 s → 60 s → 2 min … up to 2 h). Wrong credentials typed into a re-authentication prompt count toward it too. Wait for the window to expire. Restarting the app doesn’t help: the count is saved next to the database and only resets when you enter the correct credentials, or when the lock is changed or removed.

Changing or removing the lock asks for my current password

Even though the app is unlocked, changing the lock or running a destructive command prompts for the current credentials.

This is intentional. Re-authentication is required for changing or removing the lock, Import data, Remove my data and Factory reset, so that a compromised UI process can’t quietly disable the gate. An error starting Current credentials are required or Current app-lock credentials are required means what you typed didn’t match.

Loach keeps locking itself

The lock screen appears mid-session, not just at launch.

One of the two auto-lock triggers is on. Both live in the Auto-lock card in Settings → Security, which only appears once a lock is configured:

• Lock after inactivity - set it to Off, or to a longer interval, if a 1- or 5-minute timeout is catching you while you read a long reply. Typing, clicking, scrolling, touch and moving the mouse over Loach count as activity; watching a reply stream does not.
• Lock when minimized - turn it off if you routinely minimize Loach while it works. Native save / open dialogs don’t trigger it, so exporting or attaching a file is safe either way.

If neither is on, check you aren’t pressing Ctrl + Shift + L or typing /lock, which lock immediately. On macOS, closing the window (the red button, ⌘ + W) hides Loach rather than quitting it, and always locks it. A reply already streaming keeps running behind the lock screen - unlocking returns you to it with the tokens that arrived meanwhile. A Private Chat doesn’t survive a lock: locking wipes it, as closing it would.

macOS asks for keychain access when I unlock

Unlocking Loach brings up a macOS prompt asking to let it use its dev.loach.app keychain item - often right after an update.

Loach reads the lock from the keychain when you unlock (the lock screen itself comes up without it), and macOS can ask again after an update. Enter your login password and choose Always Allow. If you deny it, Loach can’t check your PIN or password and stays locked - try again and allow it.

The lock fired later than the timeout I set

You picked 1 minute but it took closer to 75 seconds.

Expected. The idle deadline is re-checked periodically rather than driven by one long timer, so the lock lands up to 15 seconds after the interval. Erring late is deliberate: a timer that fires early on a throttled or suspended window is the worse failure. A machine that sleeps past the interval locks the moment it wakes.

Loach opened without asking for my PIN

A lock is configured, but Loach started straight into your chats.

At launch Loach reads whether a lock is set from a small marker file next to its database, app_lock.json, so the lock screen comes up without waiting on the OS credential store. Only when that file is missing - the first launch after updating, or after it was deleted - does Loach ask the credential store instead. If that check fails - no Secret Service running on Linux, or a keyring still waiting to be unlocked - Loach starts unlocked rather than stranding you on a lock screen it can’t verify, and Settings → Security shows App lock is off for that session. An answer that takes longer than 5 seconds but finds a lock brings the lock screen up when it arrives. Make sure your keyring is running and unlocked, then restart Loach. On a managed Windows machine, see Platform for Credential Manager restrictions.