termux/termux-app · error · FileNotFoundException

Failed to create document with id

Error message

Failed to create document with id 

What it means

Thrown by TermuxDocumentsProvider.createDocument when File.mkdir() (for a directory MIME type) or File.createNewFile() (for a file) returns false, meaning the filesystem refused to create the entry. The new document id (full path) is appended so the caller knows which path failed.

Source

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

        return true;
    }

    @Override
    public String createDocument(String parentDocumentId, String mimeType, String displayName) throws FileNotFoundException {
        File newFile = new File(parentDocumentId, displayName);
        int noConflictId = 2;
        while (newFile.exists()) {
            newFile = new File(parentDocumentId, displayName + " (" + noConflictId++ + ")");
        }
        try {
            boolean succeeded;
            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);

View on GitHub (pinned to 3df69d1da1)

Solutions

1. Confirm the parent document id exists and is a writable directory before calling createDocument.
2. Ensure storage/SAF permissions are granted to the app.
3. Sanitize displayName to remove path separators and illegal characters before creation.
4. Check available disk space and SELinux denials in logcat.

Example fix

// before
if (!succeeded) {
    throw new FileNotFoundException("Failed to create document with id " + newFile.getPath());
}

// after (surface the underlying reason)
if (!succeeded) {
    String reason = newFile.getParentFile() == null ? "no parent"
        : !newFile.getParentFile().canWrite() ? "parent not writable" : "mkdir/createNewFile returned false";
    throw new FileNotFoundException("Failed to create document with id " + newFile.getPath() + " (" + reason + ")");
}

// Validate parent writability before attempting creation
File parent = new File(parentDocumentId, displayName).getParentFile();
if (parent == null || !parent.exists() || !parent.canWrite()) {
    throw new FileNotFoundException("Parent not writable: " + parent);
}
if (displayName.contains("/") || displayName.contains("\\")) {
    throw new IllegalArgumentException("displayName must not contain separators");
}

try {
    return createDocument(parentDocumentId, mimeType, displayName);
} catch (FileNotFoundException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to create document")) {
        // surface to SAF client, optionally retry with sanitized name
        throw e;
    }
    throw e;
}

When it happens

Trigger: The parent directory does not exist or is not writable; a file/dir already exists at the resolved name despite the conflict-renaming loop; disk full; permission/SELinux denial; the path is invalid for the filesystem.

Common situations: Storage permission not granted; SAF client passed an invalid display name with path separators; destination is on read-only storage; parent was deleted concurrently.

Related errors

• Failed to delete document with id
• not found
• Moving termux prefix staging to prefix directory failed
• Malformed symlink line:
• No SYMLINKS.txt encountered

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