Troubleshooting

Connected, but no cards

It is either the format or the location. Check in this order.

1. Is the file inside a directory? Files at the vault root are never cards
2. Is the first line exactly ---? That one test is what identifies a v2 card
3. Is there a closing ---? Without it, the file yields no card
4. Is there a well-formed id? 3–64 ASCII letters, digits and hyphens. No underscores
5. Does the path contain a directory starting with _ or .?
6. If the cards are still in the v1 shape, are they exactly three levels deep?

Settings → “Current status” shows how many cards were read and how many files could not be parsed.

The repository list is empty

Connecting and installing are different things. Logging in does not put the App into any repository. Use “Choose which repositories to share” in settings to open GitHub, pick your repositories, and load the list again.

The Changes tab returns 403

A GitHub App with only Contents cannot read pull requests. Worse, an issued token keeps the permissions it was approved with, so adding Pull requests: read-only to the App does not fix it on its own.

1. Approve the new permission on GitHub
2. Reconnect in the app to get a new token

Forget the second step and it stays broken after you “already added it”. The app’s 403 screen walks through both.

The connection never finishes

• The approval code is valid for 15 minutes. If it expired, start again from “Connect GitHub”
• Leaving the app mid-approval is fine; it picks the exchange back up when you return (on Mac, on the next launch)
• Device flow does not work in the browser build (used for development). Connect from the app

The token expires after 8 hours

If “user-to-server token expiration” is enabled on the GitHub App, tokens expire after the default 8 hours. This app holds no secret with which to refresh them, so it cannot extend one. The expiry is shown in settings rather than hidden.

Settings says “FSRS-5”

Not a bug. It means data/fsrs.json carries a 19-element w. Use 21 elements, or omit w, and you get FSRS-6.

At 19 elements, iOS also stops reading learning_steps (short-term becomes a fixed 1/5/10 minutes).

data/fsrs.json has no effect

Settings → “FSRS parameters” lists what was declined and why. A broken file never stops the app, so it can look as if it were silently ignored.

Synced, but nothing was sent

• Grades made unconnected, or before you ever picked a repository of your own, are not sent (trial grades)
• If another device moved the remote ahead, the push is rejected. Fetch again and sync once more
• Writes are serial and 1.1 seconds apart, so a heavy day takes a moment

Start over from scratch on this device

“Erase this device’s data” in settings removes this device’s vault, review logs and token. Nothing on GitHub changes. Grades not yet synced cannot be recovered, so sync first.

Telling us about a mismatch

This documentation is the public specification, kept in step with the apps. If it disagrees with what the app does, one of the two is wrong.

The format is developed in the open, so issues and pull requests are welcome there directly.