Audit Files
Allows for comparing and correcting files and file references in the files directory, in the database, and in content.
auditfiles
Install
composer require 'drupal/auditfiles:^4.2'
Overview
The Audit Files module helps keep files on your server in sync with those used by your Drupal site. It provides seven comprehensive reports that compare files on the server's file system, entries in the file_managed database table, file_usage table, and file field references in content entities.
The module intentionally avoids using the Drupal File API when dealing with files and their references to prevent creating additional problems while attempting to fix existing ones. It uses the Drupal Batch API to perform operations efficiently, reducing server load and preventing timeouts on large file systems.
For each discrepancy found, administrators can take corrective actions such as adding files to the database, deleting orphaned files from the server, removing stale database entries, or merging duplicate file references into a single file entity.
Features
- Seven audit reports comparing files across the file system, file_managed table, file_usage table, and content references
- Not in database report: Lists files on the server that are not tracked in the file_managed database table, with options to add them to the database or delete them from the server
- Not on server report: Lists files registered in the database but missing from the file system, with the ability to delete database entries
- Managed not used report: Shows files in file_managed that have no corresponding entries in file_usage table
- Used not managed report: Lists file usage entries where the corresponding file entity no longer exists in file_managed
- Used not referenced report: Displays files in file_usage that are no longer referenced by any content field
- Referenced not used report: Shows file references in content fields that lack corresponding file_usage entries, with options to add usage records or delete the references
- Merge file references report: Identifies duplicate file names in file_managed and allows merging multiple file entities into a single canonical file
- Batch processing for all operations to prevent timeouts on large datasets
- Configurable exclusion filters for files, extensions, and paths
- Configurable record limits and pagination for performance optimization
- Event-driven architecture allowing customization of file operations through event subscribers
Use Cases
Cleaning up after content migration
After migrating content from another CMS or Drupal version, use the 'Not in database' report to identify and register files that were copied to the server but not tracked by Drupal. Add them to the database to make them available for use in content.
Removing orphaned files to free disk space
Over time, files may accumulate on the server from deleted content or failed uploads. Use the 'Not in database' report to find these orphaned files and delete them to reclaim disk space.
Fixing broken images and downloads
When content displays broken images or downloads fail, use the 'Not on server' report to identify files registered in the database but missing from the file system. Either restore the files or clean up the database entries.
Database cleanup after module uninstallation
When modules are uninstalled without proper cleanup, they may leave orphaned entries in file_usage. Use 'Used not managed' to find and remove these stale usage records.
Consolidating duplicate file uploads
When users upload the same file multiple times creating duplicates, use the 'Merge file references' report to identify files with the same name and merge them into a single entity, updating all references automatically.
Verifying file integrity after server migration
After moving a site to a new server, run all reports to verify that the file system and database are in sync. This helps identify any files that were not properly copied during migration.
Auditing file_usage table consistency
Use 'Used not referenced' and 'Referenced not used' reports to ensure the file_usage table accurately reflects actual content references. Fix discrepancies to maintain database integrity.
Tips
- Always back up your database and files directory before performing delete or merge operations
- Start with small batches when deleting files to verify the correct items are selected
- Use exclusion settings to skip system-generated directories like css, js, and image style derivatives
- For large sites, set a reasonable maximum records limit (250-500) to prevent timeouts during initial page load
- The batch processing button appears when the maximum records limit is reached, allowing full dataset access without timeouts
- Review the 'Managed not used' report carefully - some unused files may be intentional (e.g., placeholder images, temporary uploads)
Technical Details
Admin Pages 9
/admin/config/system/auditfiles
Configure global settings for all Audit Files reports including file system paths, exclusion rules, domain handling, and report display options.
/admin/reports/auditfiles
Main landing page for all Audit Files reports. Provides links to seven specialized audit reports for analyzing and correcting file discrepancies.
/admin/reports/auditfiles/notindatabase
Lists files that exist on the server's file system but are not tracked in the file_managed database table. These may be orphan files whose parent content was deleted, files from modules that did not clean up properly, or files uploaded outside of Drupal (e.g., via FTP). The report shows file pathname, MIME type, size, and last modified date.
/admin/reports/auditfiles/notonserver
Lists files that have entries in the file_managed database table but do not exist on the server's file system. These missing files may cause broken images, failed downloads, or other display issues in content.
/admin/reports/auditfiles/managednotused
Lists files that exist in the file_managed database table but have no entries in the file_usage table. This is often normal for temporary files or files awaiting garbage collection. Review to verify expected behavior.
/admin/reports/auditfiles/usednotmanaged
Lists entries in the file_usage table where the corresponding file entity does not exist in file_managed. These are orphaned usage records referencing non-existent files.
/admin/reports/auditfiles/usednotreferenced
Lists files that have entries in the file_usage table but are no longer referenced in the content that supposedly uses them. The file field in the content entity no longer contains a reference to the file.
/admin/reports/auditfiles/referencednotused
Lists file references found in file fields attached to content entities that do not have corresponding entries in the file_usage table. These references should normally be tracked in file_usage.
/admin/reports/auditfiles/mergefilereferences
Lists all files in file_managed grouped by filename, showing potential duplicates. Allows merging multiple file entities that have the same filename into a single canonical file, consolidating usage records and saving disk space.
Permissions 2
Troubleshooting 4
Set a lower 'Maximum records' value in the Audit Files configuration page, then use the 'Load all records' button on the report page to batch process the data.
Set a lower 'Maximum records' value to limit the initial query. The batch processing feature will load remaining records without hitting PHP timeout limits.
Configure appropriate exclusion paths for directories with many files that don't need auditing (e.g., css, js, styles). Reduce items per page and maximum records settings.
Clear Drupal's cache after making changes. The module queries the database directly, but cached data might cause stale displays.
Security Notes 4
- The 'configure audit files reports' permission is marked as restricted access due to the potential impact of misconfiguration
- Delete operations are permanent and cannot be undone - verify selections carefully before confirming
- Merging files updates references across all content - ensure the canonical file choice is correct
- Consider restricting access to these reports to trusted administrators only, as they provide detailed information about the file system