{"record":{"id":"1b01f33aaecdc874","repo":"termux/termux-app","slug":"failed-to-create-document-with-id","errorCode":null,"errorMessage":"Failed to create document with id ","messagePattern":"Failed to create document with id ","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"app/src/main/java/com/termux/filepicker/TermuxDocumentsProvider.java","lineNumber":133,"sourceCode":"        return true;\n    }\n\n    @Override\n    public String createDocument(String parentDocumentId, String mimeType, String displayName) throws FileNotFoundException {\n        File newFile = new File(parentDocumentId, displayName);\n        int noConflictId = 2;\n        while (newFile.exists()) {\n            newFile = new File(parentDocumentId, displayName + \" (\" + noConflictId++ + \")\");\n        }\n        try {\n            boolean succeeded;\n            if (Document.MIME_TYPE_DIR.equals(mimeType)) {\n                succeeded = newFile.mkdir();\n            } else {\n                succeeded = newFile.createNewFile();\n            }\n            if (!succeeded) {\n                throw new FileNotFoundException(\"Failed to create document with id \" + newFile.getPath());\n            }\n        } catch (IOException e) {\n            throw new FileNotFoundException(\"Failed to create document with id \" + newFile.getPath());\n        }\n        return newFile.getPath();\n    }\n\n    @Override\n    public void deleteDocument(String documentId) throws FileNotFoundException {\n        File file = getFileForDocId(documentId);\n        if (!file.delete()) {\n            throw new FileNotFoundException(\"Failed to delete document with id \" + documentId);\n        }\n    }\n\n    @Override\n    public String getDocumentType(String documentId) throws FileNotFoundException {\n        File file = getFileForDocId(documentId);","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/termux/termux-app/blob/3df69d1da197dd9bd71a3bafd902dffd720576b4/app/src/main/java/com/termux/filepicker/TermuxDocumentsProvider.java#L115-L151","documentation":"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.","triggerScenarios":"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.","commonSituations":"Storage permission not granted; SAF client passed an invalid display name with path separators; destination is on read-only storage; parent was deleted concurrently.","solutions":["Confirm the parent document id exists and is a writable directory before calling createDocument.","Ensure storage/SAF permissions are granted to the app.","Sanitize displayName to remove path separators and illegal characters before creation.","Check available disk space and SELinux denials in logcat."],"exampleFix":"// before\nif (!succeeded) {\n    throw new FileNotFoundException(\"Failed to create document with id \" + newFile.getPath());\n}\n\n// after (surface the underlying reason)\nif (!succeeded) {\n    String reason = newFile.getParentFile() == null ? \"no parent\"\n        : !newFile.getParentFile().canWrite() ? \"parent not writable\" : \"mkdir/createNewFile returned false\";\n    throw new FileNotFoundException(\"Failed to create document with id \" + newFile.getPath() + \" (\" + reason + \")\");\n}","handlingStrategy":"try-catch","validationCode":"// Validate parent writability before attempting creation\nFile parent = new File(parentDocumentId, displayName).getParentFile();\nif (parent == null || !parent.exists() || !parent.canWrite()) {\n    throw new FileNotFoundException(\"Parent not writable: \" + parent);\n}\nif (displayName.contains(\"/\") || displayName.contains(\"\\\\\")) {\n    throw new IllegalArgumentException(\"displayName must not contain separators\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return createDocument(parentDocumentId, mimeType, displayName);\n} catch (FileNotFoundException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to create document\")) {\n        // surface to SAF client, optionally retry with sanitized name\n        throw e;\n    }\n    throw e;\n}","preventionTips":["Sanitize displayName (strip path separators) before calling createDocument.","Confirm storage permissions are granted before any SAF write.","Check parent directory existence and writability as a precondition."],"tags":["documents-provider","saf","filesystem","termux"],"backgroundTag":null,"analyzedSha":"3df69d1da197dd9bd71a3bafd902dffd720576b4","analyzedAt":"2026-08-13T22:46:28.294Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}