Home » Android » Bug when listing files with Android Storage Access framework on Lollipop

Bug when listing files with Android Storage Access framework on Lollipop

Posted by: admin May 14, 2020 Leave a comment



I have a few apps that make heavy use of SD card for file syncing. The broken external SD card access on Kitkat is still a big problem, but I am trying to resolve this with the new API available on Lollipop for the users which have this.

I successfully request and persist permission to SD card and I can list files in the root Uri returned from the grant permission activity.

See more info on how this is done here:

The user can then select any folder/subfolder for sync and I persist the folder document Uri as a string in the database.


Later, potentially after app has been restarted, the syncing of files can initiate. I then try to list the files in a subfolder (remember, I have the right permission granted and the persistence of this works and also grants me access to all children).

I then create a new instance of DocumentFile from the stored string and try to list the files:

  DocumentFile dir = DocumentFile.fromTreeUri(ctx, Uri.parse(storedUri));

The problem is listFiles always returns the children at the root Uri granted and never the children of the actual Uri I give the DocumentFile.fromTreeUri method.

I have examined the source code of DocumentFile and it seems there is a bug there, specifically I don’t see the need to modify the Uri further:

public static DocumentFile fromTreeUri(Context context, Uri treeUri) {
  final int version = Build.VERSION.SDK_INT;
  if (version >= 21) {
    return new TreeDocumentFile(null, context,
  } else {
  return null;

If we look at the source of DocumentsContractApi21.prepareTreeUri we see that rebuilds the Uri:

 public static Uri prepareTreeUri(Uri treeUri) {
   return DocumentsContract.buildDocumentUriUsingTree(treeUri,

And the methods it calls:

 public static Uri buildDocumentUriUsingTree(Uri treeUri, String documentId) {
   return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)

 public static String getTreeDocumentId(Uri documentUri) {
   final List<String> paths = documentUri.getPathSegments();
   if (paths.size() >= 2 && PATH_TREE.equals(paths.get(0))) {
     return paths.get(1);
   throw new IllegalArgumentException("Invalid URI: " + documentUri);

The found document Id by getTreeDocumentId will always correspond to the root Uri id, no matter what Uri the methods is called with. This makes it impossible to list children of sub folders using the provided framework methods.


Please fix the fromTreeUri method to not always use the root document Uri id.

Doing the following ugly hack fixes the issue, which I would really prefer not to.

  Class<?> c = Class.forName("android.support.v4.provider.TreeDocumentFile");
  Constructor<?> constructor = c.getDeclaredConstructor(DocumentFile.class, Context.class, Uri.class);

  DocumenFile dir = (DocumentFile) constructor.newInstance(null, mCtx, treeUri);
How to&Answers:

The underlying bug seems to be fixed. I also encountered that problem and without any code changes it works now with version 1.0.1 of the documentfile package.

dependencies {
    implementation 'androidx.documentfile:documentfile:1.0.1'