TeamNewPipe/NewPipe · error · IOException

Cannot create the file

Error message

Cannot create the file

What it means

Thrown in the 'safe' file-creation path of StoredFileHelper: the constructor calls docTree.createFile(mime, filename) on a DocumentFile tree and the call returns null, meaning the DocumentsProvider could not create a child document. The 'safe' path is used when the caller guarantees the filename is not already in use, so a null result is not a conflict — it is a provider-level failure (no permission, no space, provider error, or unsupported operation).

Source

Thrown at app/src/main/java/org/schabi/newpipe/streams/io/StoredFileHelper.java:92

            this.sourceTree = parent.toString();
        }

        this.tag = tag;
    }

    StoredFileHelper(@Nullable final Context context, final DocumentFile tree,
                     final String filename, final String mime, final boolean safe)
            throws IOException {
        this.docTree = tree;
        this.context = context;

        final DocumentFile res;

        if (safe) {
            // no conflicts (the filename is not in use)
            res = this.docTree.createFile(mime, filename);
            if (res == null) {
                throw new IOException("Cannot create the file");
            }
        } else {
            res = createSAF(context, mime, filename);
        }

        this.docFile = res;

        this.source = docFile.getUri().toString();
        this.sourceTree = docTree.getUri().toString();

        this.srcName = this.docFile.getName();
        this.srcType = this.docFile.getType();
    }

    StoredFileHelper(final Path location, final String filename, final String mime)
            throws IOException {
        ioPath = location.resolve(filename);

View on GitHub (pinned to 9e8be09156)

Solutions

1. Verify write permission on the tree URI is still persisted (getPersistedUriPermissions) before attempting creation.
2. Check available storage space on the target volume before writing.
3. Sanitize the filename (strip illegal characters, reserved names) before calling createFile.
4. Fall back to a different storage location (app-specific external dir) if the SAF tree is unavailable.

// Before safe-mode file creation, verify write permission and space:
List<UriPermission> perms = context.getContentResolver().getPersistedUriPermissions();
boolean canWrite = perms.stream().anyMatch(p -> p.getUri().equals(treeUri) && p.isWritePermission());
if (!canWrite || getAvailableBytes(treeUri) < minNeeded) {
    throw new IOException("Cannot write to download location");
}

try {
    StoredFileHelper helper = new StoredFileHelper(context, tree, filename, mime, true);
} catch (IOException e) {
    if ("Cannot create the file".equals(e.getMessage())) {
        // provider refused creation — notify user, offer fallback location
        promptForNewLocation();
    } else throw e;
}

When it happens

Trigger: StoredFileHelper is constructed with safe=true; docTree.createFile(mime, filename) returns null. This occurs when the underlying DocumentsProvider rejects the creation: the tree URI no longer grants write permission, the storage is full/read-only, the provider does not support createDocument, or the filename is illegal for the filesystem.

Common situations: Download target folder on an SD card that was mounted read-only or unmounted; the persistable write permission was revoked by the user or cleared on app data wipe; storage full; a cloud provider (Google Drive SAF) that does not support createFile with the requested MIME/filename; filename containing characters the provider's filesystem rejects.

Related errors

• Failed to create the tree from Uri
• SAF not available
• Directory with the same name found but cannot delete
• Cannot create a temporal file
• Cannot get the ParcelFileDescriptor for

AI-assisted analysis of TeamNewPipe/NewPipe@9e8be09156 (2026-08-14). Data as JSON: /api/errors/a3b678d7dcce227f. Report an issue: GitHub.