This guide covers common recovery steps for Cosimo's portable builds.

Before Changing Files

Close Cosimo before copying, replacing, or deleting deck and review database files. The review database is a SQLite file, and closing Cosimo avoids copying it while a write is in progress.

Cosimo normally allows only one GUI instance to use the same portable profile at a time. If a second copy refuses to start because the profile is already in use, close the first Cosimo window. If Cosimo crashed or was terminated, the operating-system lock should be released when the old process exits; if the message persists, check Task Manager or your process list for a remaining cosimo.exe.

For the default deck, the main files are:

• decks/deck.cosimo-deck
• decks/deck.reviews.sqlite3
• decks/deck/, if you use review audio
• cosimo.ini
• backups/index.txt
• backups/review-db-index.txt

For another deck, the review database sits beside the deck and uses the same base name. For example, spanish.cosimo-deck uses spanish.reviews.sqlite3.

Deck Parse Errors

If Cosimo cannot parse a deck, open the .cosimo-deck file in a text editor and check the card separators:

• --- separates the prompt from the response.
• =number= ends a card and preserves its review history.
• Older === card endings are accepted, but Cosimo upgrades them to numbered endings when it can open and save the deck.

When adding new cards directly in a text editor, use === instead of choosing your own card number. Keep existing =number= endings on existing cards.

Each card needs a non-empty prompt and a non-empty response. If a prompt or response accidentally contains a separator line by itself, Cosimo treats that as deck structure rather than card text.

Restoring Card Text

Automatic deck backups contain card text only. They do not contain review history.

To restore card text:

1. Close Cosimo.
2. Open backups/index.txt.
3. Find the backup file whose original path matches the deck you want to restore.
4. Copy that backup file over the active .cosimo-deck file.
5. Start Cosimo again.

If you also need scheduling history, restore the matching .reviews.sqlite3 file from an external backup or from Cosimo's retained review database backup.

Restoring a Full Deck Bundle

Use File -> Restore Full Deck to restore a compressed bundle into Cosimo's decks directory. Cosimo checks the zip before restoring and shows the deck file name, number of cards, audio file count, total file count, and whether the bundle contains review history.

If the restore would overwrite an existing deck, Cosimo asks for confirmation and writes a full compressed backup of the current target deck before replacing files. That backup includes the target review database when one exists. If sidecar files would be overwritten but no matching target deck exists to back up, Cosimo refuses the restore instead of overwriting those files.

Restoring a bundle can still cause data loss. It may replace newer card text, newer audio files, a newer audio-manifest.tsv, or newer scheduling and rating history in the .reviews.sqlite3 file. Bundles made with Export Full Deck or Full Deck Backup do not contain the review database; bundles made with Export Full Deck with Study History do. If a restore fails because the review database is locked, close other Cosimo windows or tools using that database and try again.

Review Database Integrity and Consistency Errors

Cosimo checks the review database with SQLite when it opens a deck. If the database fails the integrity check, Cosimo stops before migrating or writing the deck.

Cosimo also checks whether the review database is logically consistent with the deck that is being opened. For example, it rejects broken review-pass links, invalid stored rating or scheduling values, and active reversible cards whose responses collide with another active reversible card. Old review history for removed cards, including removed reverse cards, is allowed to remain dormant.

To recover:

1. Close Cosimo.
2. Find the active review database. For the default deck it is decks/deck.reviews.sqlite3.
3. If the error mentions duplicated responses for active reversible cards, use a deck backup or manual database repair so that at most one card from that duplicated-response set has an active generated reverse card. If Cosimo can still open the deck, the ready-list Duplicated responses filter can help find the conflicting cards.
4. For other integrity or consistency errors, move the damaged .reviews.sqlite3 file aside.
5. Restore a known-good .reviews.sqlite3 file.
6. Start Cosimo again.

If review database backups are enabled, backups/review-db-index.txt maps the retained database backup file to the original database path. Copy the matching backup over the damaged .reviews.sqlite3 file.

If you have no usable review database backup, you can remove the damaged .reviews.sqlite3 file. Cosimo will create a new review database, but previous ratings, scheduling state, and review history will be lost.

Review Audio Does Not Play

Review audio supports sidecar audio files in Cosimo's same-stem deck audio directory. Check that Tools -> Options -> Audio during study is not set to No audio, and that the file is in the same-stem directory beside the deck. Windows builds can play Opus, MP3, and WAV files. Non-Windows builds currently play WAV and MP3.

For example, card 1 in decks/Indonesian.cosimo-deck uses:

• decks/Indonesian/1.prompt.opus
• decks/Indonesian/1.response.opus
• decks/Indonesian/1.prompt.mp3
• decks/Indonesian/1.response.wav

Manual audio, including imported Anki MP3 files and untracked user files, wins over generated audio for the same card side. Within manual audio, or within generated audio when there is no manual file for that side, Cosimo prefers WAV, then MP3, then Opus on Windows.

Generated reverse cards reuse those files with prompt and response swapped. Cosimo's automatic deck-content and review-database backups do not include these audio files; full-deck bundle backups do. Windows packages include voice.exe, which can generate Opus or WAV files from installed OneCore or SAPI voices; see the user guide for the command-line workflow. Exam mode can use prompt audio while answering questions. During exam grading or exact-exam answer review, Tools -> Options -> Automatically play audio during exam grading and review controls whether Cosimo automatically plays the prompt, the expected response, both, or neither; Ctrl+P plays prompt audio followed by response audio when those files exist.

Current audio generation creates missing files in the selected generation format, which defaults to Opus. If a prompt or response side already has manual audio, including an imported MP3 or an untracked user file, voice.exe leaves that side untouched and does not create a generated file in another format. Manifest-tracked generated audio may be regenerated or converted when card text, voice metadata, or the selected generation format changes. Keep your own backup of manually recorded or edited audio files, or use a full-deck bundle backup, because Cosimo's automatic deck-content and review-database backups do not include them. For decks whose audio you maintain manually, set Manual audio deck (protect against automatic audio generation) in Deck -> Edit Deck Metadata. This writes audio_generation=disabled, disables Tools -> Generate Audio, and makes voice.exe refuse to generate audio for that deck.

Backup Settings

Deck backups are configured in Tools -> Options:

• Full keeps every automatic deck-content backup.
• Last only keeps only the newest automatic deck-content backup for each original deck path.
• None disables automatic deck-content backups.

Review database backups are configured separately:

• On session start refreshes one retained review database backup when a study session starts.
• Off disables review database backups.

Automatic full deck backups are configured separately:

• Daily writes one retained compressed backup per deck path when Cosimo starts or opens a deck, if the retained backup is older than 24 hours. It includes the deck file, sidecar directory, and review database.
• Off disables automatic full deck backups.

The retained review database backup and retained full deck backup are separate from numbered deck-content backups.

A balanced everyday policy is deck backups Last only or None, review database backups On session start, automatic full deck backups Daily, and frequent sync when you use more than one device. This puts the strongest automatic protection on review history and sidecar audio while avoiding a large pile of redundant deck-text backups.

On USB sticks, SD cards, and other write-limited flash media, avoid Full deck backup history and repeated manual full-deck bundles unless you need them. Cosimo deliberately keeps durable writes for review answers and file replacement, so lowering backup churn is the safer way to reduce wear.

Tools -> Wipe Backup Directory empties the whole backups directory after a warning. It deletes files and folders whether or not Cosimo generated or indexed them, so use it only after copying out anything you still need.

Runtime State

Cosimo stores portable application state in cosimo.ini beside the executable. This file contains settings and the last opened deck path.

Older beta builds used cosimo-settings.txt and cosimo-last-open-deck.txt. If Cosimo finds either file, it writes their contents into cosimo.ini and then removes the old files.

If Cosimo opens the wrong deck on startup, close Cosimo and edit or remove the last_open_deck entry in cosimo.ini.

Locked or Read-Only Files

If Cosimo cannot save a deck, settings file, report, backup, or review database change:

• Make sure the file is not open in another program.
• Check that the folder is writable.
• On portable installs, avoid running from a read-only location.
• Close Cosimo before copying files from decks or backups.
• Back up any sidecar audio directory yourself, or use a full-deck bundle backup. Automatic deck-content and review-database backups do not include audio files.

Cosimo blocks deck overwrites when required deck backups or backup index writes fail. If this happens, fix the file or folder permission problem and try the card edit again.

If a review answer cannot be recorded, Cosimo leaves the current card in the study session so the answer is not silently lost. If a study session summary cannot be recorded, the individual card answers may still have been saved, but later pass-level analysis may be incomplete.

Startup Cannot Open a Deck

If Cosimo starts with no open deck, the startup message should name the deck file and review database it tried to use. This can happen when the default decks folder cannot be created, the selected deck cannot be read, or the review database cannot be opened or created.

Cosimo should then offer to open another deck or quit. If you choose to open another deck, you can select an existing .cosimo-deck file or choose a new path and let Cosimo create an empty deck there. If that also fails, Cosimo shows the new error and offers the same open-or-quit choice again.

To recover:

1. Try opening another deck from the startup prompt.
2. Check that the named folder is writable and is not on read-only media.
3. Close other programs that may be using the named deck or review database.
4. If the review database is damaged and you have a backup, restore it.
5. Restart Cosimo after correcting the file or folder problem.

Screen Reader Notes

The ready-screen prompt list may announce the selected item twice with some screen reader and wxWidgets combinations. This is a known native-control behaviour. Once focus is inside the list, arrow-key navigation should still work normally.

Bug Reports

When reporting a problem, include:

• Cosimo version.
• Operating system version.
• Screen reader and version, if the problem involves accessibility.
• Whether the deck is the default deck or another deck path.
• The exact error message.
• Whether cosimo.ini, backups/index.txt, or backups/review-db-index.txt exists.
• The steps that led to the problem.