Skip to main content
This guide covers solutions to common issues you might encounter while using OpenComic.

​
Installation and startup issues

Windows:
  • Run as administrator
  • Check Windows SmartScreen isn’t blocking the app
  • Install Visual C++ Redistributables
  • Disable antivirus temporarily to test
macOS:
  • Right-click and select “Open” to bypass Gatekeeper on first launch
  • Check System Preferences → Security & Privacy for blocked apps
  • For non-notarized builds, run: xattr -cr /Applications/OpenComic.app
Linux:
  • Ensure executable permissions: chmod +x OpenComic.AppImage
  • Install required dependencies (see below)
  • Check if running from a filesystem that supports execution
Install required libraries:Debian/Ubuntu:
sudo apt-get install libgtk-3-0 libnotify4 libnss3 libxss1 \
  libxtst6 xdg-utils libatspi2.0-0 libdrm2 libgbm1 libxcb-dri3-0
Fedora/RHEL:
sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils \
  at-spi2-core libdrm mesa-libgbm libxcb
Arch:
sudo pacman -S gtk3 libnotify nss libxss libxtst xdg-utils \
  at-spi2-core libdrm mesa libxcb
  1. Delete configuration folder:
    • Windows: %APPDATA%/OpenComic
    • Linux: ~/.config/OpenComic
    • macOS: ~/Library/Application Support/OpenComic
  2. Restart OpenComic
  3. If issue persists, check console for error messages
  4. Report the issue with logs on GitHub
  • Update graphics drivers
  • Disable hardware acceleration in Settings
  • Try running with --disable-gpu flag: 
    # Windows
OpenComic.exe --disable-gpu

# Linux
./OpenComic.AppImage --disable-gpu

​
Comic loading issues

  1. Verify the folder is added to library paths in Settings
  2. Check file formats are supported (CBZ, CBR, CB7, PDF, EPUB, etc.)
  3. Ensure files aren’t corrupted - test opening them manually
  4. Try refreshing the library (F5)
  5. Check file permissions - OpenComic needs read access
CBR files require RAR extraction support:
  • OpenComic includes 7zip-bin which supports most RAR files
  • Ensure RAR5 encrypted archives are using supported encryption
  • For password-protected archives, enter password when prompted
  • Try re-packaging as CBZ if issues persist
  • Update to the latest OpenComic version
  • Check if PDF is encrypted or password-protected
  • Large PDFs may take time to load - wait for processing
  • Corrupted PDFs won’t load - verify file integrity
EPUB support is in alpha stage and may have issues.
  • EPUB support is experimental
  • Complex layouts may not render perfectly
  • Fixed-layout EPUBs work better than reflowable
  • Consider converting to PDF for better compatibility
  • Check image format is supported
  • Update OpenComic to latest version for new format support
  • File may be corrupted - test extraction manually
  • Try changing image interpolation method in Settings
  • Disable AI upscaling if enabled

​
Performance issues

Possible solutions:
  1. Adjust cache settings in Settings → Performance
  2. Disable image enhancements (AI upscaling, colorization)
  3. Change interpolation method to faster option (nearest)
  4. Reduce preview quality
  5. Close other resource-intensive applications
  6. For large archives, extract first before reading
  • Reduce image cache size in Settings
  • Disable page preloading
  • Close other applications
  • Restart OpenComic periodically
  • Check for memory leaks (report if found)
  • Disable hardware acceleration
  • Reduce animation effects
  • Lower image quality settings
  • Check system resources (CPU, RAM, disk)
  • Update graphics drivers
  • Disable background music if playing
  • Check thumbnail cache folder has write permissions
  • Clear thumbnail cache and regenerate
  • Increase thumbnail generation timeout in Settings
  • For remote libraries (FTP, SMB), ensure stable connection

​
Display and rendering issues

  • Change interpolation method to higher quality (lanczos3)
  • Disable “not enlarge more than original size” option
  • Check if source images are low resolution
  • Enable AI upscaling for better quality (slower)
  • Use rotation shortcuts: Ctrl+R (all pages) or Shift+R (horizontals)
  • Check auto-rotation settings
  • Manually rotate in page layout menu
  • Enable “Do not apply to horizontals” for mixed layouts
  • Adjust blank page settings if pages are misaligned
  • Some comics need manual single/double page configuration
  • Reset color adjustments in reading menu
  • Check brightness, saturation, contrast sliders
  • Disable sepia, negative, or invert colors filters
  • Disable colorization if applied to B&W images
  • Verify manga mode is enabled (Ctrl+M)
  • Check “Invert tap zones in manga” setting
  • Reading direction should be right-to-left
  • Arrow keys automatically invert in manga mode

​
Remote server connections

  • Verify server address, port, username, and password
  • Test connection with a dedicated FTP client first
  • Check firewall settings on both client and server
  • Ensure server supports the protocol (FTP, FTPS, SFTP)
  • For SFTP, verify SSH keys if using key authentication
  • Use format: smb://server/share/path
  • Provide credentials when prompted
  • Test access through file explorer first
  • Check network connectivity
  • Ensure SMB/CIFS is enabled on server
  • On Windows, use UNC path: \\\\server\\share
  • Verify URL format: webdav://server/path or webdavs:// for HTTPS
  • Check authentication credentials
  • Test with WebDAV client first
  • Verify server supports WebDAV protocol
  • Check CORS settings if accessing from web
  • Verify OPDS feed URL is correct
  • Check if feed requires authentication
  • Test feed URL in web browser
  • Some OPDS servers may be slow - wait for timeout
  • Check server is online and accessible

​
Input and controls

  • Check if another application is capturing the keys
  • Verify shortcuts in Settings → Shortcuts
  • Try restoring default shortcuts
  • Check if input field is focused (shortcuts disabled when typing)
  • Some shortcuts may conflict with system shortcuts
  • Connect gamepad before launching OpenComic
  • Check if gamepad input is enabled in Settings
  • Verify gamepad works in other applications
  • Try reconnecting the gamepad
  • Restart OpenComic
  • Check mouse wheel shortcuts in Settings
  • Verify no modifier keys are stuck (Ctrl, Shift, Alt)
  • Test in different reading modes
  • Clear and reconfigure mouse shortcuts
  • Touch support varies by platform
  • Try using mouse/keyboard shortcuts instead
  • Check trackpad settings in system preferences
  • Update trackpad drivers

​
Tracking and synchronization

  • Verify you’re logged in to the service
  • Check API credentials in Settings
  • Ensure comic metadata includes tracking ID
  • Network issues can prevent sync - check connection
  • Some comics may not be in the tracking database
  • Check database file permissions
  • Verify storage location is writable
  • Database corruption - try deleting and recreating
  • In portable mode, ensure app-data folder is writable
  • Same as reading progress issues
  • Export bookmarks as backup
  • Check if running from read-only location

​
Audio issues

  • Place music files in comic folder (MP3, OGG, etc.)
  • Check if audio files are named correctly
  • Verify audio isn’t muted in app or system
  • Check supported formats: MP3, M4A, OGG, OPUS, WAV, FLAC
  • Try different audio format if one isn’t working
  • Update audio codecs on your system
  • Check file isn’t corrupted
  • Lower audio quality/bitrate
  • Restart OpenComic

​
Miscellaneous issues

  • Check config folder has write permissions
  • Running from CD or read-only media won’t save settings
  • Use portable mode if on restricted system
  • Antivirus may be blocking config writes
  • Press M key to toggle magnifying glass
  • Click and drag to move it
  • Adjust size and zoom in Settings
  • Disable if causing performance issues
  • Enable Discord Rich Presence in Settings
  • Ensure Discord is running
  • Restart both OpenComic and Discord
  • Check Discord privacy settings allow activity status
  • AI upscaling requires compatible hardware
  • Check AI model files are present
  • May require additional GPU resources
  • Disable if causing crashes or performance issues
  • Update to latest OpenComic version

​
Getting help

If your issue isn’t covered here:
1

Check the documentation

Review other guides and the README for additional information
2

Search existing issues

Check GitHub Issues to see if others have reported similar problems
3

Gather information

  • OpenComic version
  • Operating system and version
  • Steps to reproduce the issue
  • Error messages or screenshots
  • Console logs (if available)
4

Report the issue

Create a new issue on GitHub with detailed information

​
Debug mode

To enable debug logging for troubleshooting: Windows: 
OpenComic.exe --debug
Linux: 
./OpenComic.AppImage --debug
macOS: 
/Applications/OpenComic.app/Contents/MacOS/OpenComic --debug
Logs will be output to the console and can help identify issues.

​
Common log locations

  • Windows: %APPDATA%/OpenComic/logs
  • Linux: ~/.config/OpenComic/logs
  • macOS: ~/Library/Application Support/OpenComic/logs
Include relevant log entries when reporting issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us