Manually Change Aperture Referenced Files Volume

If you have had issues with Apple’s Aperture using referenced files then this post may be of some help.  In my previous posts here and here I detailed the issues that I have been experiencing and some of the steps I tried to get back working.  If, like me, you are still banging your head against the wall, you may want to consider manually updating the Aperture Library Database file.

The process described below is for more advanced/daring users.  I’ve tried to recount everything I’ve done, but may have left some bits out.  Please be careful and understand all the steps below before proceeding.  As always YMMV.

For this procedure to work, you will need to have a file stored on the new location of your referenced images that Aperture successfully knows about.  Without it you will not have the proper UUID that Aperture uses to locate the images.  I suggest moving a test/temporary image to the volume you want your referenced images to be stored.

The db file is in a slightly different location than for iPhoto but is not too hard to find.  Right click your Aperture Library and select ‘Show Package Contents’.  In the directory window navigate to Database > apdb > Library.apdb.

Here is where things get scary.  You will want to be EXTREMELY careful with this file.  Please proceed at your own risk, I make no promises that this will work for you.  I suggest making backups, and backups of the backups of this file.

You will need to manually edit the database in SQLLite3.  I changed the filename from Library.apdb to Library.apdb.ORIG and then copied out that file to the root of my HD.

I used SQLLite Manager to run the commands against my DB.  It is a nice little plugin for Firefox that worked really well.  Open SQLLite Manager and select the Libaray.apdb file that you copied out onto your drive.  (You have to have moved the library file as SQLLite Manager will not be able to look into the contents of your Aperture Library)

Below are the commands that I used to update the file path for my referenced images.

--This command will show you the UUID of the volume where your images were stored as well as the directory path.
SELECT filevolumeuuid, imagepath FROM rkmaster

You will need to check the filevolumeuuid field for images that are not stored in your Library.  Images that are stored outside the library will have a value in this field.  It will be something long and cryptic and will not be a readable name.  Copy out this value into a text file.  You will also need to note the UUID of the volume where you moved the test/temp image above.  This is the new UUID you will be changing to later.

In my case, since I moved my images to a temp folder at the root of a dive, I only needed to add a folder name to the beginning of my directory location.  The first command below concatenates the folder name to the beginning of each ‘imagepath’ record where the record is on the original referenced volume.

--This command updates the directory path to your temp location.
UPDATE rkmaster SET imagepath = '<AddNewFolderPathToBeginningOfImagePath/>' || imagePath WHERE filevolumeuuid = '<OldFileVolumeUUID>'
--This command will change the UUID to the new volume where your images are stored.
UPDATE rkmaster SET filevolumeuuid = '<NewFileVolumeUUID>'  WHERE filevolumeuuid = '<OldFileVolumeUUID>'
--This command will should show you the updated UUID and directory path. SELECT filevolumeuuid, imagepath FROM rkmaster

Once I had completed the above, I renamed the file back to Library.apdb and moved it back to the proper location in the Aperture Library.  After launching I was able to verify that all the images show as connected on the new path that I just manually changed.

In my case, I just wanted to get everything under Aperture control again, so I selected all images in my library, and ran the ‘Consolidate Masters’ command to get all the Masters loaded back into the Aperture Library itself and away from the ‘Managed’ structure.  This cleaned out the files from my temp location and left me with a fully operational library that will hopefully be free of these type of issues moving forward.

The last step I recommend is backup, backup, backup.  And then verify that your backup will work!  For me a got a nice drive dock that allows me to swap in any SATA drive I want.  With that I run TimeMachine.  I also backup to SDLT tape every month.  Like I said, I’m a backup freak!  You cant be too careful.

7 thoughts on “Manually Change Aperture Referenced Files Volume”

  1. I am trying to do the same thing in the new Apple Photos app.. which lacks any kind of “Locate Referenced Files” function, like Aperture does. I just need to change fileVolumeUuid (as I moved my Library from one laptop to another), my imagePath doesn’t need to change.

    It appears that Photos version of Library.apdb uses a different schema from iPhoto/Aperture. When I attempt to execute:

    UPDATE rkmaster SET fileVolumeUuid = ‘xxxxxxxx’

    .. I get the following error:

    SQLiteManager: Likely SQL syntax error: UPDATE rkmaster SET fileVolumeUuid = ‘bDw6FNHRQFWYgGI%aSU2mA’ [ no such function: RKMaster_notifyRidIndexUpdate ]
    Exception Name: NS_ERROR_FAILURE
    Exception Message: Component returned failure code: 0x80004005 (NS_ERROR_FAILURE) [mozIStorageConnection.createStatement]

    I have no trouble updating imagePath or other attributes. I don’t know enough about SQL – anyone know what might be preventing me from updating fileVolumeUuid in the latest Photos database??

  2. You can reconnect to originals moved to a new location by using the Aperture command File > Locate Referenced Files. For example, if the files were on an external drive and you copied them to your internal drive, follow this procedure:

    1. Disconnect the external drive. This is very important because you must not allow Aperture to find the files on the external drive.

    2. Select in the Aperture browser all of the offline files. You can do this my using the filter to show only offline files, then select all.

    3. Select the File > Locate Referenced Files command. This displays the dialog named Reference Files in Selection. The dialog contains a list of volumes for the selected files, plus the status of the volumes and a list of the selected files. It also has a Show Reconnect Options button. When you press this button, the dialog expands to show reconnect options and the button name changes to Hide Reconnect Options.

    4. Select from the list the name of the offline volume. This is in the lefthand column of the dialog. In this example, this would be the name of the external drive you disconnected in Step 1.

    5. Use the Show Reconnect Options button. This expands the dialog. The left column of the reconnect options shows a list of volumes and folders.

    6. Navigate to the folder containing the images you want to reconnect. Sometimes you cannot select the exact folder, but only its parent or sibling. For example, if the folder is named “Japan 2015” and its resides in a folder named “Travel Photos” you may not be able to select “Japan 2015”. This is okay. Just select its parent, in this case “Travel Photos”. This may be a bug or a feature. I have no idea, but don’t worry about it.

    7. Use the Reconnect All button. If the button is not available, press and hold the Option/Alt button on your keyboard and use the Reconnect All button. Aperture finds and reconnects the images.


    Let me know if this does not work for you. I use Aperture for photo management, meta data editing and very lightweight adjustments so am not an expert.

  3. This worked great for me, thanks!

    In my case, I had moved my Aperture library to a different drive, and every photo was “lost” even though it was in the right place within the library in the Masters folder.

    The “Reconnect All” function in Aperture seems completely hopeless when you have a complex folder hierarchy. But your SQL approach above worked great. I second the warnings about being ultra careful to backup the database!!

    After following the above steps, I also had to do the following to get everything regenerated and linked correctly:

    UPDATE rkmaster SET fileIsReference=1 WHERE fileIsReference==0


    UPDATE rkmaster SET isMissing=0 WHERE isMissing==1

    The first command reminds Aperture that these files do in fact reference real files on the filesystem. The second reminds Aperture that these files are no longer missing.

    After that, go to Photos view (so you view all pictures) in Aperture, select all photos, and select Photos > Generate Thumbnails – then wait a while and everything will be back to normal.

    This may be of use to other readers of this article.

  4. I found your post very helpful to manually relocate Aperture referenced masters. My situation was different. I didn’t need to prepend the path as you did; I needed to remove part of the path. This query searches for instances of the old path and replaces matching strings with the new path.

    Old path: referenced/Users/username/Pictures/Aperture/
    New path: Users/username/Pictures/Aperture/

    UPDATE rkmaster SET imagePath = replace(imagePath, ‘referenced/Users/’, ‘Users/’) WHERE fileVolumeUuid = ”

    Thanks for posting!

Leave a Reply

Your email address will not be published. Required fields are marked *