Quick Troubleshooting Guide

When encountering issues, search by symptom → follow troubleshooting steps → resolve quickly.

Table of Contents

• Symptom 1: Software Won't Start
• Symptom 2: Scanning/Indexing Stuck or Failed
• Symptom 3: Photos Won't Display or Display Incorrectly
• Symptom 4: Search Results Inaccurate or Empty
• Symptom 5: Face Recognition Inaccurate
• Symptom 6: Software Runs Slowly
• Symptom 7: High Memory/CPU Usage
• Symptom 8: Docker Deployment Failed
• Symptom 9: Activation Failed
• General Troubleshooting Steps

Symptom 1: Software Won't Start

Troubleshooting Steps

1. Check system requirements

   • Windows 10+ / Windows Server 2012 R2+ / macOS Apple Silicon / Ubuntu 24.04+
   • 64-bit CPU, 4 GB+ memory

2. Windows Server 2012 R2 requires runtime library

   This OS version lacks the required Visual C++ runtime by default, which prevents the software from starting. Please install:

   Visual C++ Redistributable for Visual Studio 2015

   Download and install vc_redist.x64.exe.

3. Check installation integrity

   • Re-download the installer and reinstall (overwrite)

4. Check log files

   • Locate the log file in the data directory
   • Search for [ERROR] or panic keywords to pinpoint the issue

5. Reset data directory (last resort)

   • Back up the data directory
   • Delete the data directory and restart
   • Note: This loses index and configuration data; original photo files are unaffected

Related Sections

• Installation & System Requirements
• System Settings

Symptom 2: Scanning/Indexing Stuck or Failed

Symptoms

• Scan progress bar stalls for a long time
• Index progress bar gets stuck
• Error prompts indicating scan failure

Troubleshooting Steps

Restart → Check folder permissions → Check disk space → Isolate testing → Refresh index → Rebuild index

1. Restart the Software (Top Priority)

Completed indexing is never lost. The software automatically detects the interruption on launch and continues from the breakpoint, skipping already-processed photos.

Controlled by Settings → Index Settings → "Auto-recover Index" (enabled by default).

2. Check Folder Permissions

Ensure Photocatalyst has read permissions for the added folders. Verify accessibility in the file manager.

3. Check Disk Space

Ensure sufficient free disk space (at least 1 GB recommended).

4. Isolate and Test

• Remove all folders
• Add one small folder (few photos) for testing
• If works, gradually add larger folders in batches

5. Refresh Index (Manual Recovery)

Menu → Refresh Index. Manually triggers recovery from the current state — skips completed, processes only remaining.

6. Rebuild Index (Last Resort)

Settings → Data Rebuild → Rebuild Index. Full rebuild — takes a long time.

Prevention

• Choose AI capabilities: Configure AI capabilities before adding folders for the first time (Settings → AI Config). For basic management only, choose the Lightweight preset — avoiding face/semantic/OCR greatly boosts speed
• Add photos in batches for large collections (no more than 10,000 per batch)
• Set reasonable ignore rules to exclude unwanted files
• Set a minimum image size filter (default 96 px)

Related Sections

• Photo Import & Indexing
• Scan Settings

Symptom 3: Photos Won't Display or Display Incorrectly

Symptoms

• Thumbnails appear blank or show a broken icon
• Photo preview is black screen
• Certain format photos don't display
• EXIF info is missing

Troubleshooting Steps

Verify original file → Check format support → Check FFmpeg → Clear cache → Rebuild index

1. Verify Original File

Open the original file with the system default image viewer to confirm the file is not corrupted.

2. Check Format Support

Confirm the file format is in the supported list. Commonly unsupported formats require additional setup:

3. Install FFmpeg

HEIC/HEIF requires FFmpeg for decoding: Settings → System Settings → FFmpeg Download/Install.

4. Clear Thumbnail Cache

Delete cache files in the data directory and restart the software to regenerate thumbnails.

5. Rebuild Index

Settings → Data Rebuild → Rebuild Index — re-scans and regenerates thumbnails.

Related Sections

• Photo Browsing
• Supported Image Formats

Symptom 4: Search Results Inaccurate or Empty

Symptoms

• No results when searching certain keywords
• Search-by-image results are irrelevant
• AI semantic search results are way off
• Face search results are inaccurate

Troubleshooting Steps

Confirm index status → Adjust search parameters → Optimize search terms → Rebuild index

1. Confirm Photos Are Indexed

Check the status bar to ensure all photos have been scanned. Unindexed photos cannot be searched.

2. Adjust Search Parameters

3. Optimize Search Techniques

• File info search: Use wildcards * and ?
• Scene content search: Separate multiple subjects with commas, e.g., cat, indoor, sofa
• Face search: Use front-facing, well-lit photos
• Advanced search: Use combined conditions for precise filtering

4. Rebuild Index (Last Resort)

Settings → Data Rebuild → Rebuild Index. Most effective when data is corrupted.

Related Sections

• Search
• Data Rebuild

Symptom 5: Face Recognition Inaccurate

Symptoms

• Face detection misses faces
• Same person split into multiple characters
• Different people merged into the same character
• Non-face areas misdetected as faces

Troubleshooting Steps

Adjust parameters → Manually correct → Merge/split → Rebuild face groups

1. Adjust Face Parameters

Settings → AI Config → Face Settings:

• Recognition threshold: Lower (e.g., 0.15) detects more faces; higher (e.g., 0.3) reduces false detections
• Tip: Make small adjustments first, test, then fine-tune

2. Manual Correction

3. Handle Unclassified Faces

• View unclassified faces on the Characters page
• Manually assign to existing characters
• Or batch create new characters

4. Rebuild Face Groups

Settings → Data Rebuild → Rebuild Groups → Faces. Completely re-clusters all characters.

Related Sections

• Face Recognition
• AI Config

Symptom 6: Software Runs Slowly

Symptoms

• Interface responds sluggishly
• Photos load slowly
• View switching lags

Troubleshooting Steps

Hardware check → Software settings optimization → Database optimization → Data cleanup

1. Hardware Optimization

2. Software Settings Optimization

3. Database Optimization

Run once a month: Settings → System Settings → Optimize Database.

4. Data Cleanup

• Remove missing file records: Settings → Remove Missing
• Empty photos in the trash
• Clean up duplicate photos

Related Sections

• Performance Optimization Tips

Symptom 7: High Memory/CPU Usage

Troubleshooting Steps

1. Reduce concurrency

   • Settings → AI Config → Processing Mode → Sequential (not Parallel)

2. Limit pending photo count

   • Add photos in batches; avoid adding tens of thousands at once

3. Adjust AI capability scope

   • Settings → AI Config → Inference Capabilities → Select as needed (Core/Face/Text/Semantic)

4. Restart the software

   • Restart after heavy data processing to free memory fragmentation

Symptom 8: Docker Deployment Failed

Symptoms

• Container exits immediately after starting
• Port is inaccessible
• Data directory permission errors

Troubleshooting Steps

Check logs → Check port → Check mounts → Check permissions

1. Check Container Logs

docker-compose logs -f

Search for [ERROR] to pinpoint the issue.

2. Check Port

• Ensure the host port (e.g., 10242) is not in use
• Allow the port through firewall
• Access URL format: http://<server-ip>:10242

3. Check Volume Mounts

volumes:
  - /your/photos:/photos:ro    # Ensure host path exists and has read permission
  - ./data:/app/data            # Ensure data directory has write permission

• The :ro suffix on the photo directory means read-only — do not omit
• Use absolute paths for host paths

4. Check Image Architecture

5. Check Disk Space

df -h

Ensure sufficient space for index data.

Related Sections

• Docker Deployment
• docker-arm64

Symptom 9: Activation Failed

Desktop Version Troubleshooting

1. Confirm the request code was copied completely without omissions
2. Confirm activation code is entered correctly (case-sensitive)
3. Confirm activation code matches the request code
4. Restart the software after activation

Docker Version Troubleshooting

1. Confirm the container has internet access (required for online activation)
2. Confirm activation code is entered correctly
3. Check activation status: Menu → Help → About

Related Sections

• Software Activation

General Troubleshooting Steps

For issues not listed above, follow this order:

1. Restart the software —— Most problems are resolved by restarting
   ↓ If restart doesn't help
2. Contact the vendor for technical support (attach log files)

Getting More Help

• Help docs: Menu → Help → Docs
• Check for updates: Menu → Help → Check for Updates
• View version: Menu → Help → About
• Log files: Menu → Help → Open Log File
• Data directory: Settings → System Settings → Open Data Directory

When submitting an issue report, please include relevant error messages from the log files and the software version number.

If the issue persists, please contact the vendor for technical support.