Permissions and File Access¶

Goal¶

Help you distinguish between application logic problems and system file-access restrictions.

Supported Platforms¶

iOS
macOS

Intended Audience¶

Users blocked by file visibility or destination-access problems
Testers separating permission issues from app-logic failures

Prerequisites¶

A concrete import, export, or drag-and-drop path has already failed or behaved unexpectedly
You can retry the same path and observe whether the system shows a permission prompt

Steps¶

Retry the same path and watch for system permission prompts.
Confirm that the source or destination location is actually accessible to the app.
Check whether the failure matches a platform-specific rule such as PNG -> Photos on iOS.
Record the exact error text and the rough location involved.

Result¶

You can tell whether the problem comes from system access restrictions or from a different application-level issue.

Most Common Permission Scenarios¶

the file picker cannot see the target data
the system refuses access after a file is selected
export fails when writing to the destination
saving to Photos fails on iOS
drag and drop is blocked by the system

Recommended Troubleshooting Order¶

Check whether the system showed a permission prompt.
Confirm the target data is stored in a location the app can access.
On iOS, remember that the Photos destination only applies to PNG.
On macOS, verify that the save-panel destination is writable.
Retry the exact same path and confirm whether the problem reproduces.

A Few Implementation Facts That Matter¶

If the user cancels file picking intentionally, the app does not treat it as an error alert.
Drag-and-drop import depends on the system providing a valid fileURL; without permission, the app cannot resolve one.
On iOS, exporting to Photos is a distinct path and is not the same as a normal Files export.

What to Record¶

platform and system version
rough destination location
whether the system showed a permission prompt
whether the failure happened during import, export, or drag and drop
the exact error text

Common Questions¶

The file exists. Why can’t the picker see it?¶

Most of the time, this is caused by system access-scope restrictions rather than the app being unaware of the file. Move the file to a more directly accessible location and try again.

If export fails, does that always mean export is broken?¶

No. A destination that is not writable, missing permissions, or a mismatch between format and destination can also cause export failure.

Why does saving to Photos only support PNG?¶

Because the current implementation only wires the Photos path to PNG.

Last Verified¶

2026-04-17