Why didn't my file get imported into my Library?

Why didn't my file get imported into my Library?

PhotoStructure has a number of filters that all must pass for a photo or video to be added to your library.

📁 Directory filters

PhotoStructure doesn’t import any files from system directories, hidden directories, or NoMedia directories.

🎯 File filters

  1. The file must be a JPEG, PNG, digital camera raw format, or a video format that FFmpeg can decode.

  2. If the JPEG is found to be corrupt it will be skipped. This may be due to bitrot or file truncation due to a failed backup.

  3. If the image is too small, it will be skipped. The default minimum dimension is 480 pixels for images, and 240 pixels for videos. The default minimum filesize is 50 KB. These defaults can be changed with the minImageDimension, minVideoDimension, and minAssetFileSizeBytes library settings, or the PS_MIN_IMAGE_DIMENSION, PS_MIN_VIDEO_DIMENSION, and PS_MIN_ASSET_SIZE_BYTES environment variables.

  4. If a file is too large, it will be skipped. This mostly applies to videos, and prevents your NAS from filling up with transcoded versions of that 45 minute piano recital that you’ll never watch. This defaults to 500 MB, and can be changed with the maxAssetFileSizeBytes library setting.

  5. PhotoStructure will refuse to walk into directories that have the same path element more than 7 times. This helps avoid getting stuck in infinite filesystem loops caused by symbolic links.

  6. HEIC/HEIF photos require additional codec support. See the Video and HEIF/HEIC support guide for setup instructions.

❓ Why didn’t an individual file get imported?

Two ways to see why PhotoStructure skipped a file:

📊 Via sync reports

PhotoStructure writes a detailed sync report during each sync. Every file and directory gets a row explaining exactly what happened.

Look for your file’s path in the report — the state and details fields will tell you whether it was excluded (and why), unavailable (volume not mounted), failed (with the error), or something else entirely.

🔧 Via “File Diagnostics”

PhotoStructure v2026.1.1 added a “File Diagnostics” download option to the Sync activity page.

  1. From the home page, click the upper-left-corner navigation icon and choose “Sync activity”.
  2. Tap “More Actions”, and pick “Download File Diagnostics”.
  3. Type the filename or path of the missing file, and click “Download ZIP”.

The ZIP file will contain all logfiles and Sync Report rows explaining why the file was not imported (if it was scanned at all).

Realize that if the file is in a directory that was never scanned because of any of the above directory filters, there will be no information about it.

💻 Via command-line tools

If you’re comfortable with the terminal, use PhotoStructure’s info and list command-line tools.

⚙️ excludeGlobs setting

The excludeGlobs setting lets you exclude directory and file name patterns from your library.

See also