Garbage-Collecting Orphaned Binaries

Updated: November 8, 2022

The binary files attached to documents are not stored in the database but using a specialized binary store (typically filesystem-based or S3), and are not removed like documents (see Trash Service).


Binary files are not immediately deleted when their containing document is deleted because the binary store uses a de-duplication strategy which means that the same binary file may be referenced by several documents. To avoid complex locking or reference counting strategies, they are simply garbage-collected when there remains no reference to them (they are orphaned).

Manually - Using the Web interface

The garbage collection is done by an explicit administration step:

  1. In the JSF UI go to Admin > System Information > Repository binaries.
  2. Check the Delete orphaned binaries check box. If you just want to gather statistics about what it going to be deleted, don't check this box and go to next step.
  3. Click on Mark orphaned binaries.

Programmatically - Using the Nuxeo Shell or Java Code

import org.nuxeo.ecm.core.blob.DocumentBlobManager;
import org.nuxeo.ecm.core.blob.binary.BinaryManagerStatus;

DocumentBlobManager docBlobManager = Framework.getService(DocumentBlobManager.class);
if (!docBlobManager.isBinariesGarbageCollectionInProgress()) {
    BinaryManagerStatus binaryManagerStatus = docBlobManager.garbageCollectBinaries(true);
    println("Orphaned binaries garbage collecting result: " + binaryManagerStatus);
} else {
    println("Orphaned binaries garbage collecting is already in progress.");

Related Documentation