Skip to content

[Bug]: Bug Report: The preview database record is out of sync with the actual preview file, preventing the thumbnail from being regenerated. #63513

Open
Bug
Open
[Bug]: Bug Report: The preview database record is out of sync with the actual preview file, preventing the thumbnail from being regenerated.#63513
Bug
Labels
0. Needs triagePending check for reproducibility or if it fits our roadmap34-feedbackbug

Description

@mrliuchang-crypto
mrliuchang-crypto
opened on Aug 24, 2026

⚠️ This issue respects the following points: ⚠️

Bug description

Bug Report: Preview 数据库记录与实际预览文件不同步，导致缩略图无法重新生成

Report prepared by: ChatGPT, based on the user's actual server environment, command outputs, database inspection and reproduction tests.

Date: 2026-08-24

1. Environment

  • Hardware: Raspberry Pi 5, 8 GB RAM
  • Storage: 1 TB NVMe SSD / MergerFS storage pool
  • OS: Linux
  • Nextcloud: 34.0.3.2
  • Nextcloud version string: 34.0.3
  • PreviewGenerator: 5.14.0
  • Database: MariaDB/MySQL
  • PHP: PHP 8.x
  • Preview providers enabled:
    • OC\Preview\Movie
    • OC\Preview\MP4
    • OC\Preview\MKV
    • OC\Preview\AVI
    • OC\Preview\Image
    • OC\Preview\HEIC
  • FFmpeg: /usr/bin/ffmpeg
  • Nextcloud previews enabled
  • Redis configured for local/locking cache

The server was previously migrated from a Raspberry Pi 3 environment to a Raspberry Pi 5. Preview-generation settings had also been optimized previously to reduce the workload on the Pi 3.

2. Problem Description

Some files displayed without thumbnails/previews even though the source files themselves were valid and accessible.

The problem was especially apparent when browsing the photo library from the Nextcloud mobile client. Refreshing/browsing the affected directories did not result in the expected preview generation.

The initial assumption was that the preview generator was failing to generate previews.

Further investigation showed a more specific problem:

The oc_previews database table contained records describing previews that no longer existed on the filesystem.

As a result, Nextcloud believed that the requested preview already existed. When the preview was requested again, the system attempted to use the database record and the corresponding preview path, but the actual JPEG file was missing.

This creates an inconsistent state:

Database:
oc_previews
    ↓
preview record exists
    ↓
Nextcloud believes preview exists

Filesystem:
appdata_*/preview/...
    ↓
corresponding JPEG does NOT exist

This prevents normal regeneration.

3. Reproduction Example

One affected file was:

fileid: 879196
name: 26-08-22 15-24-15 9028.mov
mimetype: video/quicktime
size: 13.3 MB

The source file was confirmed to be valid:

codec_name=hevc
width=1920
height=1080

The file was accessible from:

/mnt/pool/nextcloud_data/admin/files/Photos/2026/08/26-08-22 15-24-15 9028.mov

The database contained multiple preview records for this file.

For example:

width  height
1080   1920
256    256
36     64
144    256
576    1024
256    455
1024   1820
64     64

However, the corresponding filesystem preview for 144x256 did not exist.

Running:

sudo -u www-data php /var/www/nextcloud/occ preview:generate 879196 --size=144 -vvv

reported:

preview generated

but the expected file:

144-256.jpg

was not created.

The database still contained the preview record.

4. Confirmation of the Database/File Mismatch

The problematic preview record was identified:

file_id = 879196
width   = 144
height  = 256

The corresponding filesystem file was missing.

After manually deleting the stale database record:

DELETE FROM oc_previews
WHERE id=120906814083026944;

the same command was executed again:

sudo -u www-data php /var/www/nextcloud/occ preview:generate 879196 -vvv

This time the preview was successfully generated.

The database then contained a new record:

width  = 144
height = 256

and the filesystem contained:

144-256.jpg

The generated file was confirmed with:

ls -lah /mnt/pool/nextcloud_data/appdata_ocfy6fwmnciv/preview/.../879196/

Result included:

-rw-r--r-- 1 www-data www-data 7.5K ... 144-256.jpg

The Nextcloud mobile client was then refreshed and the missing preview appeared correctly.

5. Second File Reproduction

A second file was tested:

fileid: 879184

The database contained:

48 x 64
64 x 64
192 x 256
256 x 256
256 x 341
768 x 1024
1024 x 1365
3024 x 4032

The filesystem contained previews for:

48-64.jpg
64-64-crop.jpg
256-256-crop.jpg
256-341.jpg
768-1024.jpg
3024-4032-max.jpg

but the 192 x 256 preview was missing from the filesystem.

The database record for 192 x 256 was deleted:

DELETE FROM oc_previews
WHERE id=120896547211169792;

Then:

sudo -u www-data php /var/www/nextcloud/occ preview:generate 879184 -vvv

was executed.

The result was that the stale database record disappeared and was not immediately recreated when the preview was not requested.

This confirmed the same database/filesystem inconsistency.

6. Full Preview Reset

Because the problem affected a large portion of the photo library, deleting individual database records was not practical.

The server was placed into maintenance mode:

sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on

The status confirmed:

maintenance: true

Then:

sudo -u www-data php /var/www/nextcloud/occ preview:cleanup

was executed.

The command reported:

Previews removed

Afterwards:

SELECT COUNT(*) AS preview_records
FROM oc_previews;

returned:

preview_records
0

The preview directory was also gone:

/mnt/pool/nextcloud_data/appdata_ocfy6fwmnciv/preview/

The server was then returned to normal operation:

sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off

7. Full Regeneration Test

After the complete cleanup, preview generation was tested against:

/admin/files/Photos/2026/08

using:

sudo -u www-data php /var/www/nextcloud/occ preview:generate-all --path="/admin/files/Photos/2026/08" -vv

The command successfully processed JPG files as well as MOV and MP4 files.

Examples from the output:

Generating previews for ... 8990.jpg
Generating previews for ... 8991.jpg
Generating previews for ... 8992.jpg
...
Generating previews for ... 9027.mov
Generating previews for ... 9028.mov
Generating previews for ... 2026_0822_122912_502.MP4
Generating previews for ... 2026_0822_123213_503.MP4
Generating previews for ... 2026_0822_123513_504.MP4

No database/file mismatch occurred during this clean regeneration test.

8. Preview Configuration Used During Testing

To reduce unnecessary preview generation while still providing useful thumbnails/previews, the PreviewGenerator configuration was adjusted to:

squareSizes = 64 256
fillWidthHeightSizes = 256 4096
coverWidthHeightSizes = ""
squareUncroppedSizes = ""
widthSizes = ""
heightSizes = ""

System preview limits were:

preview_max_x = 2048
preview_max_y = 2048

The effective PreviewGenerator specification became:

64x64 crop
256x256 crop
256x256 fill

This configuration was intentionally simplified because the server contains a large photo/video library.

9. Expected Behavior

When a preview database record exists but the corresponding preview file is missing, Nextcloud/PreviewGenerator should detect the inconsistency and regenerate the preview automatically.

For example:

DB record exists
+
preview JPEG missing

should be treated as:

stale preview record

and the stale record should be removed/replaced before attempting to read the missing preview file.

The user should not be required to manually manipulate the oc_previews table.

10. Actual Behavior

Instead, the stale database record can prevent successful regeneration.

The system can report:

preview generated

or otherwise proceed without creating the missing file, while the stale database record remains.

The user is then left with:

oc_previews:
    preview record exists

Filesystem:
    preview file missing

Repeated requests do not necessarily repair the situation.

The problem is therefore persistent until the database record is removed.

11. Suggested Fix

The preview-generation code should verify that an existing preview database record has a corresponding valid preview file before treating it as an existing preview.

Conceptually:

if preview database record exists:
    if preview file exists:
        use existing preview
    else:
        remove stale database record
        generate preview again

Alternatively, preview cleanup/reconciliation could periodically detect:

DB record -> missing filesystem file

and remove stale entries.

A database/file consistency check would also be useful for large installations.

12. Why This Is Important

This issue becomes particularly problematic on large photo libraries.

A single missing preview is easy to repair manually.

However, when hundreds or thousands of stale records exist, manually deleting individual records is impractical.

The problem can also be difficult to diagnose because:

  • the original media file is valid;
  • FFmpeg/ImageMagick/etc. can process the file;
  • the preview generator may report successful processing;
  • the database still claims the preview exists;
  • the actual preview file is missing;
  • browsing the library does not necessarily repair the inconsistency.

This can make the issue appear to be a client/mobile/browser problem when it is actually a server-side preview database/filesystem consistency problem.

13. Related Upstream Issues

This report appears closely related to an existing Nextcloud Server issue:

Nextcloud Server #63349 — “Preview generation fails when DB entry exists, but local file does not.”

That issue describes essentially the same failure mode: a preview database entry exists while the corresponding local preview file is missing, preventing normal regeneration. It was opened on August 18, 2026 and is currently open. citeturn0search8

There is also a related PreviewGenerator issue:

PreviewGenerator #670 — “Cleaning generated previews doesn't clean up database entries.”

This issue was opened July 27, 2026 and is currently open. citeturn0search0

The PreviewGenerator documentation currently recommends occ preview:cleanup for resetting/regenerating previews on Nextcloud 31 and newer. citeturn0search1

14. Additional Observation

The behavior was reproduced with both:

  • video preview (fileid 879196)
  • image preview (fileid 879184)

Therefore the problem does not appear to be specific to HEVC/MOV/MP4 decoding.

The source files were valid and accessible.

The decisive test was:

stale DB record + missing preview file
        ↓
preview generation does not repair it

delete stale DB record
        ↓
preview generation succeeds
        ↓
new DB record created
        ↓
actual JPEG created
        ↓
client displays preview

This strongly indicates that the root cause is preview metadata/storage consistency rather than the media files themselves.

15. Recommended Diagnostic Information for Developers

If further investigation is required, the following information can be useful:

Nextcloud version: 34.0.3.2
PreviewGenerator: 5.14.0
Database: MariaDB/MySQL
Storage: MergerFS
Preview storage: appdata_*/preview
PHP: 8.x
FFmpeg: /usr/bin/ffmpeg

The most useful diagnostic test is to compare:

SELECT id,file_id,width,height,size,etag
FROM oc_previews
WHERE file_id=<FILE_ID>;

against:

find <appdata>/preview -path "*/<FILE_ID>/*" -type f -ls

If a database record exists without the corresponding file, the inconsistency can be reproduced.

Conclusion

The investigation demonstrates that the missing-thumbnail problem was caused by stale/inconsistent entries in oc_previews.

The database contained preview records whose corresponding JPEG preview files were absent.

Deleting the stale database record allowed the preview generator to recreate the preview successfully. A complete preview cleanup followed by a fresh preview:generate-all also restored normal preview generation.

The recommended fix is for Nextcloud/PreviewGenerator to automatically detect and recover from a preview database record whose corresponding preview file no longer exists, instead of treating the stale database record as a valid existing preview.

This bug report was generated by ChatGPT from the user's actual Nextcloud 34.0.3.2 server logs, database queries, filesystem checks, configuration, reproduction steps, and successful remediation tests.

Steps to reproduce

Expected behavior

  1. Use Nextcloud 34.0.3.2 with the Preview Generator app 5.14.0 enabled.

  2. Have an image or video file that already has preview records in the oc_previews database table.

  3. Make one of the corresponding preview files disappear from the filesystem while leaving its database record in oc_previews.

    For example, for file_id=879184, the database contained a preview record for 192 x 256, but the corresponding preview file was missing from the appdata_*/preview/.../879184/ directory.

  4. Verify that the preview record still exists in the database:

sudo mysql nextcloud -e "
SELECT id,file_id,width,height,size,etag
FROM oc_previews
WHERE file_id=879184
ORDER BY width,height;
"

  1. Verify that the corresponding preview file does not exist on disk.

  2. Run preview generation for the file:

sudo -u www-data php /var/www/nextcloud/occ preview:generate 879184 -vvv
  1. The command reports:
preview generated

However, the missing preview is not regenerated.

  1. Check the database again. The stale preview record is still present:
sudo mysql nextcloud -e "
SELECT id,file_id,width,height,size,etag
FROM oc_previews
WHERE file_id=879184
AND width=192
AND height=256;
"

The query returns no newly generated preview after the failed regeneration attempt, while the original preview state remains inconsistent with the filesystem.

  1. Delete the stale preview database record:
sudo mysql nextcloud -e "
DELETE FROM oc_previews
WHERE id=120896547211169792;
"
  1. Run the exact same preview generation command again:
sudo -u www-data php /var/www/nextcloud/occ preview:generate 879184 -vvv
  1. This time the preview is successfully generated.

The database now contains a new preview record for the requested dimensions, and the corresponding JPEG file appears in the appdata_*/preview/.../879184/ directory.

  1. Refreshing the Nextcloud web interface or mobile client then displays the preview correctly.

  2. The same behavior was independently reproduced with another file (file_id=879196), where a missing 144 x 256 preview could only be regenerated after deleting the stale oc_previews database record.

Expected behavior:

If a preview database record exists but the corresponding preview file is missing, preview:generate should detect the stale database record, remove or invalidate it, and regenerate the missing preview automatically.

Actual behavior:

preview:generate reports preview generated, but the missing preview is not created while the stale database state remains. Manual deletion of the corresponding oc_previews record is required before the preview can be generated successfully.

Nextcloud Server version

34

Operating system

None

PHP engine version

None

Web server

Apache (supported)

Database engine version

MariaDB

Is this bug present after an update or on a fresh install?

Updated from a MINOR version (ex. 32.0.1 to 32.0.2)

Are you using the Nextcloud Server Encryption module?

None

What user-backends are you using?

  • Default user-backend (database)
  • LDAP/ Active Directory
  • SSO - SAML
  • Other

Configuration report

sudo -u www-data php occ config:list system
php occ config:list system
./occ config:list system
{
    "system": {
        "instanceid": "***REMOVED SENSITIVE VALUE***",
        "passwordsalt": "***REMOVED SENSITIVE VALUE***",
        "secret": "***REMOVED SENSITIVE VALUE***",
        "trusted_domains": [
            "192.168.0.102",
            "nextcloud.circuitwater.com",
            "192.168.0.103"
        ],
        "datadirectory": "***REMOVED SENSITIVE VALUE***",
        "dbtype": "mysql",
        "version": "34.0.3.2",
        "overwrite.cli.url": "https:\/\/nextcloud.circuitwater.com",
        "dbname": "***REMOVED SENSITIVE VALUE***",
        "dbhost": "***REMOVED SENSITIVE VALUE***",
        "dbtableprefix": "oc_",
        "mysql.utf8mb4": true,
        "dbuser": "***REMOVED SENSITIVE VALUE***",
        "dbpassword": "***REMOVED SENSITIVE VALUE***",
        "installed": true,
        "maintenance": false,
        "theme": "",
        "loglevel": 2,
        "memories.db.triggers.fcu": true,
        "memories.exiftool": "\/var\/www\/nextcloud\/apps\/memories\/bin-ext\/exiftool-aarch64-glibc",
        "memories.vod.path": "\/var\/www\/nextcloud\/apps\/memories\/bin-ext\/go-vod-aarch64",
        "preview_ffmpeg_path": "\/usr\/bin\/ffmpeg",
        "enabledPreviewProviders": [
            "OC\\Preview\\Movie",
            "OC\\Preview\\MP4",
            "OC\\Preview\\MKV",
            "OC\\Preview\\AVI",
            "OC\\Preview\\Image",
            "OC\\Preview\\HEIC"
        ],
        "enable_previews": true,
        "memories.vod.ffmpeg": "\/usr\/bin\/ffmpeg",
        "memories.vod.ffprobe": "\/usr\/bin\/ffprobe",
        "maintenance_window_start": 5,
        "memcache.local": "\\OC\\Memcache\\Redis",
        "memcache.locking": "\\OC\\Memcache\\Redis",
        "redis": {
            "host": "***REMOVED SENSITIVE VALUE***",
            "port": 6379,
            "timeout": 1.5
        },
        "preview_max_x": 2048,
        "preview_max_y": 2048
    }
}
Cannot write into "config" directory!
This can usually be fixed by giving the web server write access to the config directory.

But, if you prefer to keep config.php file read only, set the option "config_is_read_only" to true in it.
See https://docs.nextcloud.com/server/34/go.php?to=admin-config
-bash: ./occ: Permission denied

List of activated Apps

sudo -u www-data php occ app:list
php occ app:list
./occ app:list
Enabled:
  - activity: 7.0.0
  - app_api: 34.0.0
  - appstore: 1.0.0
  - bruteforcesettings: 7.0.0
  - circles: 34.0.0
  - cloud_federation_api: 1.18.0
  - comments: 1.24.0
  - contactsinteraction: 1.15.0
  - dav: 1.40.0
  - federatedfilesharing: 1.24.0
  - federation: 1.24.0
  - files: 2.6.0
  - files_downloadlimit: 5.2.0
  - files_lock: 34.0.1
  - files_pdfviewer: 7.0.0-dev.0
  - files_reminders: 1.7.0
  - files_sharing: 1.26.0
  - files_trashbin: 1.24.0
  - files_versions: 1.27.0
  - firstrunwizard: 7.0.0-dev.0
  - guests: 4.9.0
  - logreader: 7.0.0
  - lookup_server_connector: 1.22.0
  - maps: 1.7.1
  - memories: 8.1.0
  - nextcloud_announcements: 6.0.0
  - notifications: 7.0.0-dev.1
  - oauth2: 1.22.0
  - office: 1.0.0
  - password_policy: 6.0.0-dev.0
  - photos: 7.0.0
  - previewgenerator: 5.14.0
  - privacy: 6.0.0-dev.1
  - profile: 1.3.0
  - provisioning_api: 1.24.0
  - recommendations: 7.0.0
  - related_resources: 5.0.0-dev.0
  - serverinfo: 6.0.0
  - settings: 1.17.0
  - sharebymail: 1.24.0
  - support: 6.0.0
  - survey_client: 6.0.0-dev.0
  - systemtags: 1.24.0
  - text: 8.0.0
  - theming: 2.9.0
  - twofactor_backupcodes: 1.23.0
  - twofactor_totp: 16.0.0
  - updatenotification: 1.24.0
  - user_status: 1.14.0
  - viewer: 7.0.0-dev.0
  - weather_status: 1.14.0
  - webhook_listeners: 1.6.0
  - workflowengine: 2.16.0
Disabled:
  - admin_audit: 1.24.0
  - dashboard: 7.14.0 (installed 7.12.0)
  - encryption: 2.22.0
  - files_external: 1.26.0
  - suspicious_login: 12.0.0-dev.0
  - twofactor_nextcloud_notification: 8.0.0
  - user_ldap: 1.25.0
Cannot write into "config" directory!
This can usually be fixed by giving the web server write access to the config directory.

But, if you prefer to keep config.php file read only, set the option "config_is_read_only" to true in it.
See https://docs.nextcloud.com/server/34/go.php?to=admin-config
-bash: ./occ: Permission denied

Nextcloud Signing status



Nextcloud Logs




Additional info


No response
Metadata
Metadata
Assignees
No one assigned
    Labels
    0. Needs triagePending check for reproducibility or if it fits our roadmap34-feedbackbug
    Type
    Bug
    Projects
    🧑‍🤝‍🧑 Community triage
    Status
    To triage
    Milestone
    No milestone
    Relationships
    None yet
    Development
    No branches or pull requests
    Issue actions