What causes "Failed to delete document with id " in termux/termux-app?

If the document is a directory, recursively delete its contents before calling deleteDocument, or implement recursive delete.

termux/termux-app · error · FileNotFoundException

Failed to delete document with id

Error message

Failed to delete document with id

What it means

Thrown by TermuxDocumentsProvider.deleteDocument when File.delete() returns false, meaning the file/directory could not be removed. Common reasons: the path is a non-empty directory, the file is locked/open, or the process lacks permission. SAF requires deleteDocument to throw FileNotFoundException on failure so the framework reports the deletion as unsuccessful.

Source

Thrown at app/src/main/java/com/termux/filepicker/TermuxDocumentsProvider.java:145

            if (Document.MIME_TYPE_DIR.equals(mimeType)) {
                succeeded = newFile.mkdir();
            } else {
                succeeded = newFile.createNewFile();
            }
            if (!succeeded) {
                throw new FileNotFoundException("Failed to create document with id " + newFile.getPath());
            }
        } catch (IOException e) {
            throw new FileNotFoundException("Failed to create document with id " + newFile.getPath());
        }
        return newFile.getPath();
    }

    @Override
    public void deleteDocument(String documentId) throws FileNotFoundException {
        File file = getFileForDocId(documentId);
        if (!file.delete()) {
            throw new FileNotFoundException("Failed to delete document with id " + documentId);
        }
    }

    @Override
    public String getDocumentType(String documentId) throws FileNotFoundException {
        File file = getFileForDocId(documentId);
        return getMimeType(file);
    }

    @Override
    public Cursor querySearchDocuments(String rootId, String query, String[] projection) throws FileNotFoundException {
        final MatrixCursor result = new MatrixCursor(projection != null ? projection : DEFAULT_DOCUMENT_PROJECTION);
        final File parent = getFileForDocId(rootId);

        // This example implementation searches file names for the query and doesn't rank search
        // results, so we can stop as soon as we find a sufficient number of matches.  Other
        // implementations might rank results and use other data about files, rather than the file
        // name, to produce a match.

View on GitHub (pinned to 3df69d1da1)

Solutions

If the document is a directory, recursively delete its contents before calling deleteDocument, or implement recursive delete.
Close any open file descriptors to the target before deletion.
Verify the path is writable and the storage is not read-only.
Check logcat for the underlying reason delete() returned false.

Example fix

// before
public void deleteDocument(String documentId) throws FileNotFoundException {
    File file = getFileForDocId(documentId);
    if (!file.delete()) {
        throw new FileNotFoundException("Failed to delete document with id " + documentId);
    }
}

// after (recursive delete for directories)
public void deleteDocument(String documentId) throws FileNotFoundException {
    File file = getFileForDocId(documentId);
    boolean ok = file.isDirectory() ? deleteRecursively(file) : file.delete();
    if (!ok) {
        throw new FileNotFoundException("Failed to delete document with id " + documentId);
    }
}

Defensive patterns

Strategy: validation

Validate before calling

File file = new File(documentId);
if (!file.exists()) {
    // nothing to delete; treat as success or signal caller
}
if (file.isDirectory() && file.list().length > 0) {
    // must empty first
    throw new IOException("Directory not empty: " + documentId);
}

Try / catch

try {
    provider.deleteDocument(documentId);
} catch (FileNotFoundException e) {
    // document already gone; acceptable in many clients
    Log.w(TAG, "Already deleted: " + documentId);
}

Prevention

Empty directories before deletion, or implement recursive delete.
Close open file descriptors to the target before deleting.
Treat FileNotFoundException on delete as 'already gone' when idempotency is acceptable.

When it happens

Trigger: Deleting a directory that still contains children (File.delete fails on non-empty dirs); deleting a file held open by another process; read-only filesystem; permission denial.

Common situations: Client requests deletion of a populated directory without emptying it first; file locked by an editor or shell; storage mounted read-only.

Related errors

AI-assisted analysis of termux/termux-app@3df69d1da1 (2026-08-13). Data as JSON: /api/errors/8d0c73daee40224a. Report an issue: GitHub.