Documentation›Integrations, data, and support
47 Data and support

Recover a Character or the Whole App

What actually brings a companion back, and which recovery routes exist in 1.8.0.

Local Waifu 1.8.0 macOS Windows
plain English first

Follow the bold button names and numbered steps. Technical names are included only when you need to recognize a model or file inside the app.

Read this before you delete anything. The recovery routes are not interchangeable, and two of the four in this chapter need to be prepared before you need them. If the app cannot open at all, jump to the section about the recovery screen.

The four routes, and when each one works

RouteWorks afterNeeds preparing in advance
Character JSON export and importThe app is reinstalled, or you are on a different computerNo. You can export at any time while the app opens
Full backup folderA crash, a bad update, a resetPartly. The backup must exist; see Chapter 39
Soul recovery codeThe encrypted soul files are lost, or you moved to a new computerYes. The code must be created and stored while you still have access
Conversation JSON exportAlmost nothing on its ownNo, but it is not a recovery method

The last row is the one people get wrong. Conversation JSON is an export for reading and archiving, not a restore. There is no control that imports it back into the app. If it is all you have, you have a readable transcript and not a companion.

Route 1: character export and import

The supported self-service route and the only one you can use entirely on your own. Chapter 15 has the full steps and Chapter 39 has the migration checklist.

Use it when the app still opens and you want that character on another installation.

If something goes wrong

If the import reports a failure, the file is damaged or was cut off during transfer. Export it again from the source installation rather than editing the JSON.

Route 2: full backup

The only route that covers everything at once: database, soul files, portraits, generated images, voice references, and settings.

Important limitation in 1.8.0: no button replaces your live data with a backup. A backup is a folder you keep, and bringing it back is a support-assisted procedure rather than a click. Do not copy a backup over a live data directory while the app is running. What you can do on your own is check that a backup is usable: Settings → Advanced → Restore a backup copies it into a new folder and verifies the soul files, without touching your live data (Chapter 39).

Use it before an update, before a reset, and before any change you are not certain about.

If something goes wrong

If the app will not start at all, stop changing anything on disk. Preserve the data directory as it is and contact support with the backup and the current state.

Route 3: the soul recovery code

This is the route for the case nothing else covers: your encrypted soul files exist, but the key that opens them is gone.

Why a separate key exists. Soul files, meaning personality, memory, and knowledge, are encrypted with a key tied to the computer you created the character on. If you copy the data directory to another computer, or the app’s secret store is lost, those files cannot be decrypted by the new installation. A recovery code wraps that key under a passphrase you choose, which makes it portable.

What a recovery code is

  • A text code that starts with LWR1:.
  • Protected by a passphrase you set, which must be at least 12 characters.
  • Machine-independent. That is the entire point of it.

How you would use one

  1. While everything still works, on the computer that holds the character, you generate the code and set the passphrase.
  2. You store the code and the passphrase in two separate safe places. A password manager for the passphrase, a printed copy or an encrypted note for the code is a reasonable split.
  3. Later, on the new or repaired installation, you open the same character, enter the code and the passphrase, and the soul files open again.

In version 1.8.0 this is not reachable from the interface. The mechanism is implemented and shipped in the application, but there is no button for it in Settings. If you are in the situation it solves, contact support and they will walk you through creating or redeeming a code.

If something goes wrong

  • A passphrase that is too short is rejected outright. The 12-character floor exists because the code can be handed around and guessed offline.
  • A pair of code and passphrase that does not match fails without damaging anything. It is an authenticated blob, so a wrong passphrase cannot produce a half-decrypted character.
  • If you lose the passphrase, the code is useless and there is no recovery from it. Store the two parts deliberately.

When the app cannot open: the recovery screen

If Local Waifu cannot open its database at start, it does not guess. It shows a screen titled Local Waifu could not open your database. and says nothing has been changed: your database, its sidecar files, and her soul files are still where they were. If it could not even check its data, a shorter screen offers Try again and Reload window.

The recovery screen offers these actions:

ActionWhat it does
Save a copy of everythingCopies the whole data folder into a new folder outside it: the database and its sidecars, her soul files, all pictures, audio and models, her key store, and a manifest. Nothing is parsed or changed. A copy includes the key store that unlocks her soul files, so keep it as private as the app’s own folder
Check the database againRead-only. If it opens now, the app restarts into its normal start
Check a restored copyPoints at a database file from a backup and checks it read-only. Nothing is installed or replaced
Show the data folderOpens the data folder
Start fresh, keep a copyFor when nothing else helps and there is no backup. Everything in the data folder (memories, chats, pictures, and keys) moves into a new folder beside it, untouched, and the app starts as on its first day. You press Yes, move it aside and start fresh to confirm. Nothing is deleted, and downloaded models stay installed
QuitCloses the app

The screen also lists which startup step failed, and for encryption problems it explains which piece is missing: for example the per-install encryption salt, the hardware identifier, or the key store (secrets.json). It does not replace any of them behind your back, because that could make her soul files permanently unreadable.

Recommended order

  1. Select Save a copy of everything first, to a drive outside the data folder.
  2. Use Check the database again once the cause is gone, such as a full disk or a moved folder.
  3. Contact support with the screen’s technical details before you use Start fresh, keep a copy.
  4. Use Start fresh, keep a copy only when you accept starting as on the first day. Your old data is kept beside the data folder, so support can still help you.

What nothing can recover

Be clear about these before you rely on any route.

  • Deleted characters. Once a character is deleted and the data is gone, no route brings it back. Export first, always.
  • A forgotten soul recovery passphrase. There is no reset for it.
  • Encrypted soul files without their key. Without the original computer’s key or a recovery code, the ciphertext stays closed.
  • Anything that was never backed up. Lumizone holds no copy of your data. There is no server-side backup to fall back on.

The order to do things if you are unsure

  1. Stop writing to the app. Every turn adds new data and makes a clean snapshot harder.
  2. Make a full backup if the app still opens.
  3. Export the character you care about most, as a second independent copy.
  4. Write down what happened, with the exact error text, and note which of the four routes above you still have available.
  5. Contact support before you reset, reinstall, or move files by hand.

Resetting is the one step that can turn a recoverable situation into an unrecoverable one. Chapter 41 explains exactly what Reset All removes.