Troubleshooting

macOS blocks the app#

Current local builds are not notarized. Review the source and the release before using Open Anyway in System Settings > Privacy & Security. Do not disable system protections globally. A corrupt download or incompatible release requires a new trusted artifact.

School connection or refresh fails#

Confirm the public HTTPS Moodle URL. Check whether the school allows mobile web services and third-party access. Maintenance and disabled services need school-side resolution. An absent directory entry can still be entered as a URL.

Reconnect expired accounts with the same identity. A cached course view can be older than the school’s current data. Open the school website to verify urgent work.

Document conversion fails#

Check the 50 MB import limit and the document format. A scanned PDF has no selectable text and needs OCR elsewhere. A complex PDF layout may convert with missing or reordered content.

The first conversion needs consent for package downloads and an available uv or Python environment. Settings > Privacy offers Retry and converter Offline mode. Cold startup can take several seconds. Test Markdown or plain text to separate conversion setup from library access.

AI or Keychain access fails#

Enable the intended provider and select an available model. Unlock saved keys after restart. If Keychain access is denied or times out, retry after granting access or choose Use without saving keys for the session.

For a CLI provider, sign in outside VStudy and confirm its resolved executable. Codex must match the pinned verified version. Never include an API key, token, private document, or full diagnostic URL in a bug report.

Storage is full or restore fails#

Free disk space before retrying. Use Settings > Storage for usage and bounded cleanup. Preserve originals and backups until you know the replacement is readable.

Restore only accepts the app’s supported portable-backup format. Invalid archives leave live data untouched. If startup recovery fails, keep the recovery directory and report the error without sharing the private backup.