How to track and interpret the results of Confluence attachment migration from v003 to v4
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
As seen in the official Hierarchical File System Attachment Storage, from Confluence 8.1 onward, a new way to store attachment data in the file system has been introduced.
This includes a new logic to determine the filesystem directory structure and has been designed to:
limit the number of entries at any single level in a directory structure
eliminate the need to move attachments between directories when a page is moved to a new location
If you're upgrading your Confluence instance from a previous version, a background task will perform the attachment migration to the new directory structure automatically, as soon as you start the instance in the new version.
However, it can be hard to understand when exactly task starts, how to track its progress and to determine if it has been completed successfully so this article is intended to provide some insights on how to confirm and interpret the attachment migration results.
Diagnosis
If you're upgrading your Confluence instance from an older version and don't want the attachment migration task to kick in, you can add the following system property to disable migrating to v4 storage and keep using the legacy ver003:
1
-Datlassian.darkfeature.confluence.disable-attachments-ver004=trueAfter upgrading your Confluence instance to version 8.1 or newer, Confluence will automatically trigger the attachment migration task from version v003 to v4. This task can be seen in atlassian-confluence.log:
1
2
3
4
5
6
7
2023-06-16 22:09:37,497 INFO [attachment-migration:thread-1] [confluence.admin.actions.AttachmentV3toV4MigrationAction] lambda$startMigration$0 Attachments migration from version 3 to version 4 has started.
2023-06-16 22:09:42,291 INFO [attachments-migration-job:thread-5] [atlassian.confluence.upgrade.AttachmentMigratorToV4] moveAttachmentToV4 Attachments migration from V3 to V4 progressed. Moved 50000 attachments since the last restart.
2023-06-16 22:09:47,374 INFO [attachments-migration-job:thread-5] [atlassian.confluence.upgrade.AttachmentMigratorToV4] moveAttachmentToV4 Attachments migration from V3 to V4 progressed. Moved 100000 attachments since the last restart.
(...)ℹ️ If your Confluence instance is restarted while the attachment migration task is still in progress, the task will resume from where it left off once the instance restarts. Attachments that have already been migrated to version 4 will not be reverted.
After the migration task is completed, the logs should show the following entry if the migration was successful for all attachments:
1
2
3
4
5
2023-06-16 22:09:48,265 INFO [attachment-migration:thread-1] [atlassian.confluence.upgrade.AttachmentMigratorToV4] notifyCompleted Attachments migration from V3 to V4 completed successfully.
2023-06-16 22:09:48,315 INFO [attachment-migration:thread-1] [atlassian.confluence.upgrade.AttachmentMigratorToV4] reportStatistics Files migrated: 111207
2023-06-16 22:09:48,315 INFO [attachment-migration:thread-1] [atlassian.confluence.upgrade.AttachmentMigratorToV4] reportStatistics Time elapsed: 10817 msAnd the ver003 attachment folder will be deleted.
If the migration failed for some attachments, the following WARN message will be seen in the logs:
1
2023-06-16 22:09:48,265 WARN [attachment-migration:thread-1] [atlassian.confluence.upgrade.AttachmentMigratorToV4] notifyCompleted Attachments migration from V3 to V4 completed with warnings. Some files failed to migrate. Please review all remaining files in <confluence-home-directory>/attachments/ver003 directory and move them to the appropriate place. You can check the report file v3-to-v4-report.log for details. This message will keep showing up until all files are removed from ver003 directory.In such a scenario, the ver003 folder will not be deleted, and all attachments that failed to migrate will still be placed within the old hierarchy.
For more information on which attachments failed to migrate, you can check the v3-to-v4-report.log file. This file will be created in the <confluence-home-directory>/attachments directory and will contain details about the migration task.
Please note that Confluence will determine its attachment directory by looking at the attachments.dir property defined in confluence.cfg.xml, which defaults to:
1
<property name="attachments.dir">${confluenceHome}/attachments</property>If you change this value to a different path that Confluence cannot access OR if this path does not contain the ver003 directory, the attachment migration task will fail and you might experience an error such as the one below:
1
2
3
4
5
6
7
2024-05-07 13:08:28,399 ERROR [Catalina-utility-1] [atlassian.config.lifecycle.LifecycleManager] panicAndShutdown Unable to start up Confluence. Fatal error during startup sequence: confluence.lifecycle.core:attachmentMigrationFromV3toV4 (Performs migration of the attachments from ver003 to ver004 storage format)
java.lang.NullPointerException
at java.base/java.util.Objects.requireNonNull(Unknown Source)
at com.atlassian.confluence.impl.pages.attachments.filesystem.AttachmentDataStorageLocationResolver.getFileLocation(AttachmentDataStorageLocationResolver.java:32)
at com.atlassian.confluence.admin.actions.AttachmentV3toV4MigrationAction.startMigration(AttachmentV3toV4MigrationAction.java:54)
at com.atlassian.confluence.admin.actions.AttachmentV3toV4MigrationAction.startup(AttachmentV3toV4MigrationAction.java:39)
at com.atlassian.confluence.impl.setup.DefaultLifecycleManager.startUp(DefaultLifecycleManager.java:52)Was this helpful?