Skip to main content

Installation and Startup Issues

Download failed or very slow?​

DesireCore installation packages are hosted on multiple download sources (CDN, build servers, GitHub Releases, etc.). The client and website automatically speed-test each source before downloading and pick the fastest one.

If you still experience download issues, you can try:

  • Check if your network connection is normal
  • Try using a VPN or switching network environments
  • Get the latest download link from the official download page (the website also supports multi-source speed testing)

macOS shows "Cannot open because the developer cannot be verified"?​

This is caused by macOS's Gatekeeper security mechanism. Solutions:

  1. Open "System Settings > Privacy & Security"
  2. Scroll to the bottom and find the prompt about DesireCore
  3. Click "Open Anyway"
  4. Or execute in terminal: xattr -cr /Applications/DesireCore.app

Windows shows "Windows protected your PC"?​

This is a prompt from Windows SmartScreen filter. Click "More info", then select "Run anyway".

White screen after startup?​

White screens are usually caused by renderer process loading failures. Try the following steps:

  1. Completely close and restart — Ensure the process has fully exited (check system tray/task manager)
  2. Clear cache — Delete the application cache directory:
    • macOS: ~/Library/Application Support/desirecore/Cache
    • Windows: %APPDATA%/desirecore/Cache
    • Linux: ~/.config/desirecore/Cache
  3. Check GPU acceleration — DesireCore uses GPU acceleration for glass material rendering. If your graphics driver is outdated, try updating it
  4. Disable hardware acceleration — If issues persist after driver update, try starting with the --disable-gpu parameter

Stuck on loading screen at startup?​

If the app stays on the loading screen, possible causes and solutions:

  • Agent service startup failed — Check if the ~/.desirecore/ directory has write permissions
  • Port occupied — DesireCore's Agent service needs to use local ports. Check if other programs are occupying the same ports
  • Data file corruption — Try renaming the ~/.desirecore/ directory as a backup (e.g., ~/.desirecore.bak/), then restart the application

How to update to the latest version?​

DesireCore supports automatic updates, checking every 5 minutes after startup:

  1. When a new version is detected, the system automatically downloads the update from the fastest source
  2. After download completes, a prompt appears — choose "Restart Now" to install
  3. Choose "Later" and you won't be prompted again for 24 hours

You can also manually check for updates on the "Settings > About" page.

Update channels: DesireCore offers Stable and Beta channels. Stable is used by default. You can switch to Beta in "Settings > About > Update Channel" to get early access to new features. See About & Updates for details.

If automatic update fails, you can manually download the latest installation package from the official website and install over the existing version.

tip

Updating will not affect your data. All Companion data is stored in the ~/.desirecore/ directory, independent of the application.

AppImage won't start on Linux?​

Make sure you have added execute permissions to the AppImage file:

chmod +x DesireCore-*.AppImage

If it still won't start, try running with the --no-sandbox parameter.

Can't find the application icon after installation?​

  • macOS: Check the /Applications/ directory
  • Windows: Check desktop shortcuts or Start Menu
  • Linux: AppImage does not automatically create desktop shortcuts. You can manually create a .desktop file or use the AppImageLauncher tool

How to completely uninstall?​

  1. Delete the application itself (same uninstall method as other apps)
  2. To also delete all data, remove the ~/.desirecore/ directory
  3. Clear API Keys stored in the system credential manager (optional)