Troubleshooting

Find solutions to common issues and problems. If you don't find an answer here, check the FAQ or contact support through Settings > Info.

Quick Fixes

Refbox won't start or crashes on launch

1. Restart your computer - Clears memory and resets system state
2. Check for updates - Ensure you're running the latest version
3. Verify system requirements - macOS 10.15+ or Windows 10+, 4GB RAM minimum
4. Reinstall Refbox - Download fresh installer from the website

Can't see Refbox on screen

1. Use the global shortcut - Press ⌃ +⌥ +R to show Refbox
2. Check display settings - Settings > Style > App > Display to verify correct monitor
3. Check if minimized - Refbox may be in your Dock/Taskbar
4. Reset window position - Close and reopen Refbox

Frames disappear or close unexpectedly

• Check if you pressed Delete - Delete closes Frames
• Check if Box was switched - Switching Boxes closes all open Frames
• Memory issues - Close other applications if system memory is low

Import & Export Issues

Can't import certain file types

Check file format support:

• See the Assets page for complete format list
• Some RAW formats may require specific camera support
• Corrupted files won't import

Try these solutions:

1. Convert the file - Use external tools to convert to a supported format (PNG, JPG, MP4, etc.)
2. Check file isn't corrupted - Open the file in another app to verify it works
3. Reduce file size - Extremely large files (>100MB) may fail; resize or compress first

Import gets stuck or fails

1. Check disk space - Ensure enough free space for the Asset
2. Close and retry - Cancel the import and try again
3. Lower import quality - Settings > Behavior > Media > Import Quality > Low
4. Import smaller batches - Instead of 100 files at once, import 10-20 at a time

Exported .refbox files are very large

This is normal - .refbox files contain full copies of all Assets in the Box. Solutions:

• Export fewer Boxes - Only export what you need
• Compress manually - ZIP the .refbox file for storage/transfer
• Lower import quality - Future imports will be smaller if using Low/Medium quality

Can't import a .refbox file

1. Check file isn't corrupted - Ensure the file downloaded completely
2. Check disk space - Need enough space for all Assets in the file
3. Try drag-and-drop - Drag the .refbox file directly into Refbox
4. Check Refbox version - .refbox files from newer versions may not work in older versions

Performance Issues

Refbox is slow or laggy

Reduce load:

1. Close unused Frames - Use "Close Frames" button in Toolbar
2. Lower import quality - Settings > Behavior > Media > Import Quality > Medium or Low
3. Split large Boxes - Break up collections with many Assets into smaller Boxes
4. Disable masonry mode - Switch to Standard layout if Box scrolling is slow

System-level fixes:

1. Close other applications - Free up RAM and CPU
2. Update graphics drivers - Especially important for 3D models and hardware acceleration
3. Restart Refbox - GPU availability is determined at launch
4. Use an SSD - HDD performance may struggle with large media files

Images take too long to load

1. Lower import quality - Settings > Behavior > Media > Import Quality
2. Reduce image file sizes - Use external tools to resize before importing
3. Check disk speed - Refbox performs much better on an SSD than an HDD
4. Close other Frames - Each open Frame consumes memory

3D models won't load or show errors

GPU issues:

1. Update graphics drivers - Download latest drivers for your GPU
2. Close GPU-intensive apps - Free up GPU memory (video editors, games, etc.)
3. Restart Refbox - GPU availability is determined at launch
4. Check system hardware acceleration - Ensure your system allows GPU access

Model issues:

• Check file format - Only OBJ, STL, GLTF, GLB, FBX supported
• Reduce model complexity - Very high-poly models may not load
• Try a different model - Verify the file isn't corrupted

Video playback is choppy

1. Use lower quality - Convert videos to lower resolution before importing
2. Close other apps - Free up CPU/GPU resources
3. Update graphics drivers - Important for hardware video decoding
4. Check video codec - Some codecs perform better than others (H.264 recommended)

Display & Visual Issues

Box sidebar won't appear

1. Check Auto Hide - Box may be hidden; hover near the screen edge or click the Reveal button
2. Check Display Target - Ensure Refbox is set to appear on the correct display Settings > Style > Display

Colors look wrong or washed out

1. Check grayscale mode - Press ⌃ +G to toggle off
2. Check opacity - Adjust opacity with T +Drag
3. Check monitor color profile - System-level color management may affect display

Transparent images have wrong background

1. Check background setting - Right-click Frame > Image Settings > Background Color
2. Choose appropriate background - White, Black, or None
3. Reset image settings - Delete and re-import Asset to reset settings

Text is blurry or hard to read

1. Adjust UI scale - Settings > Style > App > UI Scale
2. Check display scaling - System display settings may affect clarity
3. Update Refbox - UI rendering improvements in newer versions

Data & Account Issues

Lost my license key

1. See License in Settings - Settings > Account > License Key
2. Check email - Search for purchase confirmation email
3. Contact support - Email support with purchase details

License won't activate

1. Check internet connection - License activation requires internet
2. Verify license key - Ensure no typos or extra spaces
3. Check activation limit - Deactivate license on another computer first
4. Contact support - Settings > Info > Get In Touch

Data seems to be missing

1. Check correct Box - Ensure you're viewing the right Box
2. Check if Assets were deleted - Look in system trash/recycle bin for .refbox backups
3. Import backup - Restore from exported .refbox files
4. Check data folder - Verify Refbox data folder wasn't moved or deleted

Platform-Specific Issues

macOS Issues

Refbox won't open - "damaged or incomplete":

• Remove quarantine attribute: xattr -cr /Applications/Refbox.app
• Reinstall from official source

Can't grant permissions:

• System Settings > Privacy & Security > grant required permissions

Windows Issues

Windows Defender blocks Refbox:

• Add exception in Windows Security
• Ensure you downloaded from official source

Refbox window is off-screen:

• Close and reopen Refbox

Getting More Help

If these solutions don't resolve your issue:

What to include when asking for help

• Refbox version - Settings > Info
• Operating system - macOS or Windows version
• What you were doing - Steps to reproduce the issue
• Error messages - Screenshots or exact text of any errors
• When it started - After an update? Always happened?