On macOS, the libmdbx / Isar database lives under
`getApplicationDocumentsDirectory()` -> `~/Documents/...`. With iCloud
Drive's "Desktop & Documents Folders" sync enabled (a common default),
macOS protects ~/Documents with TCC and denies unsigned / sideloaded /
dev / not-yet-permission-granted builds the file access libmdbx needs
to open its database. The result is a black screen on launch with the
following error in the Flutter / app log:
[ERROR:flutter/runtime/dart_isolate.cc(1402)] Unhandled exception:
IsarError: Cannot open Environment: MdbxError (13): Permission denied
POSIX errno 13 is EACCES, raised by the OS for the access denial — not
errno 15 (ENOTBLK / "Block device required"), and not iCloud "Optimise
Mac Storage" evicting files. Verified on macOS 26.3 / Apple Silicon
with iCloud Desktop & Documents sync active: a Terminal `mkdir`+`echo
> file` to the same path succeeds (Terminal inherits the user's TCC
grant), but the unsigned dev build fails on first DB open with the
error above.
Fix: on macOS only, host the database under `getApplicationSupport-
Directory()` -> `~/Library/Application Support/<bundle id>/...`. That
location is app-private, not TCC-gated, and Apple's recommended
location for app data files. iOS, Windows, Linux are unchanged — they
keep using Documents (iOS for Files-app visibility next to backups,
Windows / Linux because Documents is the conventional location and
neither has TCC).
Includes a one-shot best-effort migration: existing macOS users with a
DB at `~/Documents/Mangayomi/databases/` have it renamed to the new
path on first launch. Migration is skipped if the new location is
non-empty so we never overwrite user data, and any failure falls back
to a fresh DB rather than crashing on launch (the user can then move
the legacy directory manually if needed). Subsequent launches skip the
migration branch because the new path already exists.
Repro
- macOS with iCloud Drive's "Desktop & Documents Folders" sync enabled
- Unsigned / sideloaded / dev build of Mangayomi (or signed build that
hasn't yet received the user's "Files and Folders > Documents" TCC
grant)
- Launch -> black screen, IsarError MdbxError (13)
Verification
- Reproduced the exact error on this branch's parent commit
(upstream/main 25c1d72c) on macOS 26.3, iCloud Desktop & Documents
sync active, captured `MdbxError (13): Permission denied`
- After this patch the same build launches cleanly and opens the
database at `~/Library/Application Support/<bundle>/Mangayomi/
databases/mangayomiDb.isar`
- Existing 15 MB Isar database from a prior run preserved through the
rebuild — no data loss
Notes
- This is a narrower follow-up to the earlier proposed Application-
Support move that was correctly rejected for being cross-platform
and missing migration. This change is gated by `Platform.isMacOS`
and migrates existing macOS users.
- Hive (`Hive.initFlutter` in main.dart) still uses Documents on
macOS. It is initialized after Isar via `_postLaunchInit` and is
unawaited, so a Hive failure wouldn't reproduce the black screen.
If Hive turns out to be affected by the same TCC denial, a
follow-up PR can move it the same way.
- Move the cacheDir creation to storage_provider from `others.dart`, `custom_extended_image_provider.dart` and `storage_usage.dart`.
- Use the correct directory, `getApplicationCacheDirectory()` instead of the `getTemporaryDirectory()` (which is being deleted by the OS regularly) for cache files.
- remove the `_cacheDownloadPath` from `storage_usage.dart` as the path is never being created in the first place, so using that path in `clearCache()` and `_getTotalDiskSpace()` is unnecessary.
- Move manageExternalStorage inside if (android), as it is Android only.
- Cache permission state, to only check for permission once per app start preventing redundant checks.
- Made `initDB` fully async to enhance efficiency and avoid sync operations
getMangaChapterDirectory() now accepts an optional mangaMainDirectory
to avoid calling getMangaMainDirectory() and thus getDirectory() twice in places where both methods are called successively.
https://docs.flutter.dev/release/breaking-changes/flutter-generate-i10n-source
The flutter tool will no longer generate a synthetic package:flutter_gen or modify the package_config.json of the app.
Applications or tools that referenced package:flutter_gen should instead reference source files generated into the app's source directory directly.
