FixMyTakeout

The .supplemental-metadata.json suffix and the 51-character cut

Exports made since about October 2024 name each photo's JSON photo.jpg.supplemental-metadata.json instead of photo.jpg.json, and when that name passes 51 characters the suffix is chopped, sometimes down to .suppl. Tools written for the old name see no JSON at all and start guessing dates.

As at 29 September 2026.

Suffix.supplemental-metadata, 22 characters
Longest JSON name51 characters including .json
When cutThe first 46 characters survive, then .json

The rule every reported example fits

Google has not documented the naming, but the examples collected in the immich-go test suite and in the GooglePhotosTakeoutHelper issue tracker all follow one pattern. Take the file's original name, add .supplemental-metadata, and if the result plus .json would be longer than 51 characters, keep only the first 46 characters before adding .json. A name that is short enough keeps the whole suffix. A name that is long enough loses all of it and ends up as the first 46 characters of the file name itself plus .json.

The count is in UTF-16 code units, which matters for emoji and some non-Latin scripts. In the immich-go tests one JSON name with emoji is 51 units long but only 29 visible characters. JavaScript's String.length counts the same units, and FixMyTakeout counts that way too.

Measured examples

Each cut name below is exactly 51 characters. The first row shows a name short enough to keep the full suffix.

FileIts JSONReported in
20161105_170829.jpg20161105_170829.jpg.supplemental-metadata.json (46, nothing cut)immich-go issue #652
MVIMG_20191230_232926.jpgMVIMG_20191230_232926.jpg.supplemental-metadat.jsonCollected from the immich-go tests and the GPTH #353 and #449 threads
PXL_20240817_202602411.mp4PXL_20240817_202602411.mp4.supplemental-metada.jsonGPTH issue #353
MVIMG_20200207_134534~2.jpgMVIMG_20200207_134534~2.jpg.supplemental-metad.jsonCollected from the immich-go tests and the GPTH #353 and #449 threads
Screenshot_20200301-161151.pngScreenshot_20200301-161151.png.supplemental-me.jsonCollected from the immich-go tests and the GPTH #353 and #449 threads
Screenshot_20231027_123303_Facebook.jpgScreenshot_20231027_123303_Facebook.jpg.supple.jsonimmich-go test suite
0bf4bdc0-0194-43e1-a85b-8823858343c7.jpg0bf4bdc0-0194-43e1-a85b-8823858343c7.jpg.suppl.jsonGPTH_Neo issue #123
Screenshot_2024-08-31-00-53-48-647_com.snapchat.jpgScreenshot_2024-08-31-00-53-48-647_com.snapcha.jsonimmich-go test suite
PXL_20230809_203449253.LONG_EXPOSURE-02.ORIGINA.jpgPXL_20230809_203449253.LONG_EXPOSURE-02.ORIGIN.jsonimmich-go test suite

The last two rows show the older cut that existed before the suffix did: the media name itself is capped at 51 characters with its extension kept, and its JSON is the first 46 characters plus .json, so the JSON name does not even contain .jpg. A comment on GPTH pull request #449 describes the same outcome for new exports once the suffix has been consumed entirely.

Examples from immich-go matcher_test.go, immich-go #652, GPTH #353 and GPTH_Neo #123.

Why tools written before October 2024 lose the dates

The original GooglePhotosTakeoutHelper looks for name.jpg.json. Issue #353, "supplemental-metadata not supported", was opened on 27 October 2024 and is still open; the last commit to that project is from 29 January 2025, and the two pull requests that add the suffix (#375 and #449) were never merged. When it finds no JSON it falls back to guessing a date from the file name, and the reporter of #353 ended up with photos dated in 1868 and 2068.

immich-go had the same gap until early 2025. Issues #652, #673, #674 and #698, all filed between 25 January and 10 February 2025, cover the suffix, the truncated forms, edited files and JSON names missing the extension, and all were fixed by 15 February 2025. Its matcher now accepts any prefix of supplemental-metadata as the segment between the last two dots, even a single letter. GooglePhotosTakeoutHelper_Neo, the maintained fork, generates the candidate names under the 51 cap and tries the supplemental form before the plain one.

If an importer or script you used was last updated before late 2024, it most likely did not see the JSON files and dated your photos some other way, most often by the file's modified time or a guess from the name.

How FixMyTakeout matches them

For each photo or video FixMyTakeout builds the names Google would have written, in this order, and looks each one up in the same folder (merged across every zip part):

  1. name.ext.supplemental-metadata.json, cut to 46 characters plus .json when longer than 51.
  2. name.ext.json, the classic form, with the same cut.
  3. Any JSON in the folder whose name is name.ext. followed by a shortened form of supplemental-metadata: .supplemental-metad, .supple, .suppl, .s. This catches exports where the cut fell at a different position than the rule predicts.

Lookups are tried with the exact name first and then case-insensitively, so IMG_0001.jpg still finds IMG_0001.JPG.supplemental-metadata.json. The report column matched_by tells you which rule fired: supplemental-metadata name, classic name or shortened supplemental-metadata name.

Check your export for the cut

  1. Sort a Photos from folder by name and find a screenshot: their names are the longest. If its JSON ends in something like .supple.json, your export has the cut.
  2. Run the export through FixMyTakeout and open fixmytakeout-report.csv. Filter matched_by for shortened supplemental-metadata name to see every file that needed the third rule.
  3. Rows with an empty sidecar column had no JSON under any rule; the date_source column shows what was used instead.