PAPERLESS_FILENAME_FORMAT does not modify the files structure into folders

by

Summary

The PAPERLESS_FILENAME_FORMAT setting in Paperless-ngx is not modifying the file structure into folders as expected. Despite setting the format to {{created_year}}/{{correspondent}}/{{document_type}}/{{title}}, the files remain in a flat structure.

Root Cause

The root cause of this issue is that changing the PAPERLESS_FILENAME_FORMAT setting requires manually running the document renamer management utility. This step is necessary to apply the new filename format to existing documents.

Why This Happens in Real Systems

This issue occurs in real systems because the PAPERLESS_FILENAME_FORMAT setting only affects new documents, not existing ones. When the setting is changed, the system does not automatically update the filenames of existing documents. This requires manual intervention using the document renamer utility.

Real-World Impact

The impact of this issue is that users may not be able to organize their documents in the desired folder structure, leading to:

  • Difficulty in finding and managing documents
  • Inefficient use of storage space
  • Potential data loss or corruption due to poor organization

Example or Code (if necessary and relevant)

To fix this issue, run the following command:

docker exec -it paperless-webserver-1 python manage.py document_renamer

This command executes the document renamer utility, which applies the new filename format to existing documents.

How Senior Engineers Fix It

Senior engineers fix this issue by:

  • Understanding the requirement to manually run the document renamer utility after changing the PAPERLESS_FILENAME_FORMAT setting
  • Using the correct command to execute the document renamer utility, as shown in the example code
  • Verifying that the folder structure is updated correctly after running the utility

Why Juniors Miss It

Junior engineers may miss this issue due to:

  • Lack of understanding of the PAPERLESS_FILENAME_FORMAT setting and its limitations
  • Failure to read the documentation carefully, which mentions the need to manually run the document renamer utility
  • Insufficient experience with management utilities and command-line interfaces