---
title: Sync reports
url: https://photostructure.com/guide/sync-reports/
description: PhotoStructure's sync reports: what they contain, where to find them, and how to use them for troubleshooting.
date: 2026-04-08
keywords: sync, import, logs, troubleshooting, library
---


Every time PhotoStructure scans your photo and video folders, it writes a **sync report**, a detailed log of every file and directory it encountered, what happened, and why.

Sync reports are your best tool for answering questions like "why wasn't this file imported?" or "what happened during the last sync?"

## 📡 System activity page

The quickest way to monitor a sync is the **System activity** page. Click the activity icon in the navigation bar to open it.

{{< figure src="/img/2026/04/system-activity-collapsed.jpg" caption="The System activity page shows sync status at a glance" >}}

### 📂 Scanned folders

Expand **Scanned folders** to see a summary for each scan path: how many files were imported, excluded, errored, or are still pending. Click **Sync now** to resync any path.

{{< figure src="/img/2026/04/system-activity-scanned-folders.jpg" caption="Per-path sync summaries" >}}

### 🔴 Live Feed

Expand **Live Feed** to watch sync events in real time. Use the filter buttons to narrow the view to imported files, files that weren't imported, or errors.

{{< figure src="/img/2026/04/system-activity-live-feed.jpg" caption="Real-time sync events with filter buttons" >}}

Each row maps to a sync report entry, with the same fields and states described below.

## 🗺️ Where to find them

You can download sync reports directly from the **Sync Reports** section of the [System activity page](#system-activity-page).

On disk, they live in your library's `.photostructure/sync-reports/` directory, organized by date. PhotoStructure creates a new report file each time it restarts or finishes syncing a scan path.

The files use the [JSON Lines](https://jsonlines.org/) format (`.jsonl`). Each line is a self-contained JSON object describing one event. You can open them in any text editor.

## 🌾 Fields

Each line contains these fields:

| Field       | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `ts`        | Timestamp in milliseconds since 1970-01-01                  |
| `at`        | Human-readable ISO timestamp                                |
| `path`      | Native file or directory path (empty for system messages)   |
| `type`      | `"file"` or `"dir"` (omitted for system messages)           |
| `state`     | What happened (see tables below)                            |
| `from`      | Which codepath produced this event                          |
| `elapsedMs` | Processing time in milliseconds (when applicable)           |
| `details`   | Why a file was excluded, what went wrong, etc.              |
| `url`       | PhotoStructure URL for the imported asset (when applicable) |
| `meta`      | Additional structured metadata                              |

The state of any path is determined by its **last row**. Sync reports are append-only, so earlier rows for the same path are superseded.

## 📄 File states

| State         | Description                                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `imported`    | The file was newly imported into your library.                                                                                                            |
| `updated`     | The file was already in your library but was re-imported because it changed on disk (different modification time or file size).                           |
| `unchanged`   | File metadata already matches your library. No changes needed.                                                                                            |
| `copied`      | The file was copied into your library's originals directory (when [automatic organization](/getting-started/automatic-library-organization/) is enabled). |
| `excluded`    | The file was excluded by your import settings (file extension, size, glob pattern, etc.). Check `details` for the reason.                                 |
| `unavailable` | The file is temporarily inaccessible, usually because its volume isn't mounted.                                                                           |
| `blocklisted` | The file caused repeated timeouts and was permanently blocked. Files with the same content hash will not be retried.                                      |
| `absent`      | The file was previously imported but no longer exists on disk. The volume is accessible, but the file is gone.                                            |
| `deleted`     | The file was rejected by filters or deleted by the user.                                                                                                  |
| `trashed`     | The file was moved to the trash at your request.                                                                                                          |
| `failed`      | Something went wrong. Check `details` for the error.                                                                                                      |
| `timeout`     | Processing took too long.                                                                                                                                 |
| `stalled`     | Processing is taking unusually long (but hasn't timed out yet).                                                                                           |
| `canceled`    | PhotoStructure was shut down during processing.                                                                                                           |
| `started`     | The file was pulled from the work queue and is being processed.                                                                                           |
| `note`        | Informational: sidecar associations, adoption events, etc.                                                                                                |
| `warning`     | Something unexpected happened. Check `details`.                                                                                                           |
| `completed`   | An asset task (finalization, repair) finished.                                                                                                            |
| `unknown`     | An internal error occurred.                                                                                                                               |

## 📁 Directory states

| State         | Description                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------- |
| `scanning`    | The directory is being read.                                                                |
| `scanned`     | The directory was read. Files within it may still be processing.                            |
| `excluded`    | The directory was excluded by settings (hidden directory, `.nomedia` marker, glob pattern). |
| `unavailable` | The directory is temporarily inaccessible (e.g., a nested mountpoint scanned separately).   |
| `completed`   | The directory and all its contents were fully processed.                                    |
| `failed`      | Reading the directory failed.                                                               |
| `timeout`     | Reading the directory took too long.                                                        |
| `stalled`     | The directory scan is taking unusually long.                                                |
| `canceled`    | PhotoStructure was shut down before the directory was processed.                            |

## 🪪 State name changes

If you have sync reports from older versions of PhotoStructure, you may see
these legacy state names. PhotoStructure reads them correctly. No action needed.

| Old name      | New name      | Notes                                               |
| ------------- | ------------- | --------------------------------------------------- |
| `synced`      | `imported`    | Renamed for clarity                                 |
| `noop`        | `unchanged`   | Renamed for clarity                                 |
| `rejected`    | `excluded`    | Merged file and directory exclusions into one state |
| `skipped`     | `unavailable` | Renamed for clarity                                 |
| `excludedDir` | `excluded`    | Now uses `excluded` with `type: "dir"`              |

## 🛠️ Working with sync reports

Filter with [ripgrep](https://github.com/BurntSushi/ripgrep):

```bash
# Find all errors
rg '"state":"failed"' *.jsonl

# Find excluded files
rg '"state":"excluded"' *.jsonl

# Find a specific file
rg 'vacation/sunset.jpg' *.jsonl
```

Process with [jq](https://jqlang.github.io/jq/):

```bash
# Show all imported files
jq 'select(.state=="imported")' *.jsonl

# Show exclusions with reasons
jq 'select(.state=="excluded") | {path, details}' *.jsonl

# Convert to CSV for Excel or LibreOffice
jq -r '[.ts,.at,.path,.type,.state,.from,.elapsedMs,.details,.url] | @csv' \
  *.jsonl > report.csv
```

## 👀 See also

- [Why is my file missing?](/guide/why-is-my-file-missing/): common reasons files aren't imported
- [Library syncing vs rebuilds](/guide/sync-vs-rebuild/): how syncs and rebuilds differ
- [Log files](/guide/log-files/): PhotoStructure's internal logs (separate from sync reports)