Troubleshooting

Common issues and solutions for BetterDiscord

This guide covers common issues you might encounter when using BetterDiscord and how to resolve them.

General troubleshooting

BetterDiscord isn't loading after installation

If BetterDiscord doesn’t appear after installation:

1. Restart Discord completely - Right-click the Discord icon in your system tray and select “Quit Discord”, then relaunch it
2. Repair your installation - Run the BetterDiscord installer again and select the “Repair” option
3. Check if Discord updated - Discord updates can overwrite BetterDiscord. Repair your installation if this happens
4. Try a different Discord channel - If you’re using Stable, try PTB or Canary, or vice versa

Make sure you’re using the official Discord desktop app, not the web version or snap package, as these aren’t supported.

BetterDiscord settings don't appear

If you don’t see BetterDiscord options in Discord settings:

1. Verify BetterDiscord is installed - Check your Discord data folder for BetterDiscord files
2. Check the console for errors - Press Ctrl+Shift+I (or Cmd+Option+I) and look for error messages in the console tab
3. Disable hardware acceleration - In Discord settings, try turning off hardware acceleration
4. Reinstall BetterDiscord - Uninstall completely and reinstall using the latest installer

Discord crashes or won't start

If Discord crashes after installing BetterDiscord:

1. Start Discord in safe mode - Hold Shift while launching Discord to disable BetterDiscord temporarily
2. Disable problematic addons - If you can access settings, disable all plugins and themes, then enable them one by one to identify the problematic addon
3. Delete cache files - Clear Discord’s cache folder (found in your Discord data directory)
4. Uninstall BetterDiscord - Use the BetterDiscord installer to uninstall, then reinstall if needed

Your addons and settings are stored separately from BetterDiscord itself, so reinstalling won’t delete your customizations.

Addon troubleshooting

Plugin won't enable or immediately disables

If a plugin won’t stay enabled:

1. Check for error messages - Look for red error text in the plugin list or console
2. Verify the plugin file - Make sure it:
   • Has the .plugin.js extension
   • Contains valid metadata (@name, @author, @description, @version)
   • Has valid JavaScript syntax
3. Check plugin compatibility - The plugin may not be compatible with your Discord version
4. Look for conflicts - Disable other plugins to see if there’s a conflict
5. Try reloading the plugin - Right-click the plugin and select “Reload”

Check the plugin’s download page or repository for known issues or updates.

Theme doesn't apply or looks broken

If a theme isn’t working correctly:

1. Make sure the theme is enabled - Check that the toggle is green
2. Check if Discord updated - Discord updates often break themes by changing class names
3. Look for theme updates - Check the theme’s download page for updated versions
4. Disable other themes - Multiple themes can conflict with each other
5. Reload the theme - Right-click the theme and select “Reload”
6. Verify the file - Ensure it has:
   • The .theme.css extension
   • Valid metadata
   • Valid CSS syntax

Some theme elements may only be visible in certain Discord areas (light mode vs dark mode, specific pages, etc.).

Addon shows as 'partially loaded' or has errors

If an addon shows error messages:

1. Read the error message - It usually indicates what’s wrong:
   • “Missing metadata” - The file needs proper JSDoc comments
   • “Syntax error” - The code has invalid JavaScript or CSS
   • “Already exists” - An addon with the same name is already loaded
2. Check the file format - Verify the metadata block is formatted correctly
3. Edit the addon - Fix the issues described in the error message
4. Delete and reinstall - Download a fresh copy of the addon

Example of proper metadata format:

/**
 * @name Plugin Name
 * @author Your Name
 * @description Plugin description
 * @version 1.0.0
 */

Addon won't load or doesn't appear in the list

If an addon file doesn’t show up:

1. Check the file location - Make sure it’s in the correct folder:
   • Plugins: BetterDiscord/plugins/
   • Themes: BetterDiscord/themes/
2. Check the file extension - Must be exactly:
   • Plugins: .plugin.js (not .plugin.js.txt or .js)
   • Themes: .theme.css (not .theme.css.txt or .css)
3. Restart Discord - Press Ctrl+R (or Cmd+R) to reload
4. Check file permissions - Ensure BetterDiscord can read the file
5. Look for duplicate files - If you have plugin.plugin.js and plugin(1).plugin.js, remove the duplicate

Custom CSS troubleshooting

Custom CSS not applying

If your custom CSS isn’t working:

1. Check if Custom CSS is enabled - Go to BetterDiscord Settings > Custom CSS and verify it’s enabled
2. Verify the file location - The file should be at:
   • Windows: %appdata%/BetterDiscord/data/stable/custom.css
   • macOS: ~/Library/Application Support/BetterDiscord/data/stable/custom.css
   • Linux: ~/.config/BetterDiscord/data/stable/custom.css
3. Check for syntax errors - Invalid CSS won’t apply. Use DevTools to check for errors
4. Verify CSS specificity - Your rules may be overridden by Discord’s styles
5. Try reloading - Press Ctrl+R (or Cmd+R) to reload Discord

Use !important as a last resort if your styles are being overridden, but try increasing selector specificity first.

Custom CSS editor won't open

If the custom CSS editor doesn’t open:

1. Check your editor settings - Go to Settings > Custom CSS and verify your open action preference
2. Try a different editor mode - Switch between built-in, detached, system, or external
3. Check file permissions - Make sure the custom.css file exists and is writable
4. Manually create the file - Create an empty custom.css file in the correct location
5. Check your system editor - If using system mode, verify you have a default text editor set

Performance issues

Discord is slow or laggy with BetterDiscord

If Discord performance is poor:

1. Disable plugins one by one - Identify resource-heavy plugins
2. Reduce the number of themes - Using many themes increases CSS processing
3. Simplify custom CSS - Complex selectors and animations can impact performance
4. Enable hardware acceleration - In Discord settings (if it’s disabled)
5. Update your addons - Newer versions may have performance improvements
6. Check your system resources - Monitor CPU and RAM usage

Some plugins that modify messages or the UI heavily can significantly impact performance, especially in busy servers.

High CPU or memory usage

If BetterDiscord is using too many resources:

1. Identify the culprit - Disable all addons and enable them one by one while monitoring usage
2. Update your addons - Outdated addons may have memory leaks
3. Clear Discord’s cache - Delete the cache folder in your Discord data directory
4. Reduce custom CSS complexity - Avoid heavy animations and complex selectors
5. Restart Discord regularly - This clears accumulated memory usage

Installation issues

Installer won't run or shows errors

If the BetterDiscord installer has issues:

1. Run as administrator (Windows) - Right-click the installer and select “Run as administrator”
2. Check antivirus - Some antivirus software may block the installer
3. Download the latest version - Get the newest installer from the official website
4. Close Discord completely - Make sure Discord isn’t running (check system tray)
5. Check permissions - Ensure you have write access to Discord’s installation folder

On Linux, you may need to make the installer executable with chmod +x BetterDiscord-Linux.AppImage.

Can't find Discord installation

If the installer can’t locate Discord:

1. Install Discord properly - Make sure you’re using the standard Discord installer
2. Use manual installation - Follow the manual installation guide in the documentation
3. Check installation path - Verify Discord is in the default location:
   • Windows: %LocalAppData%/Discord
   • macOS: /Applications/Discord.app
   • Linux: Varies by installation method
4. Try a different Discord channel - Install BetterDiscord on PTB or Canary instead

BetterDiscord doesn’t support Discord Snap packages, Flatpak, or the web version. Use the standard installer.

Platform-specific issues

Windows: Discord updates keep removing BetterDiscord

Discord updates can overwrite BetterDiscord files:

1. Re-run the installer after updates - This is normal behavior; just repair your installation
2. Create a batch script - Automate the repair process with a script that runs the installer
3. Join the Discord server - Get notified about Discord updates that might affect BetterDiscord

Keep the BetterDiscord installer handy so you can quickly repair after Discord updates.

macOS: Permission denied errors

If you get permission errors on macOS:

1. Grant full disk access - Go to System Preferences > Security & Privacy > Privacy > Full Disk Access and add Discord
2. Check file permissions - Use chmod to fix permissions on BetterDiscord folders
3. Disable SIP temporarily - Some macOS versions may require disabling System Integrity Protection (not recommended)
4. Use manual installation - This gives you more control over file permissions

Linux: AppImage won't run

If the Linux installer doesn’t work:

1. Make it executable - Run chmod +x BetterDiscord-Linux.AppImage
2. Install FUSE - AppImages require FUSE: sudo apt install fuse (or your distro’s equivalent)
3. Try manual installation - Follow the manual installation steps for Linux
4. Check Discord installation method - Make sure you’re not using Snap or Flatpak

Different Linux distributions may package Discord differently. Check the documentation for your specific distro.

Getting more help

If you still have issues after trying these solutions:

1. Check the FAQ - Visit the Discord support server for frequently asked questions
2. Search existing issues - Look through GitHub issues for similar problems
3. Provide detailed information when asking for help:
   • BetterDiscord version
   • Discord version and release channel
   • Operating system
   • List of enabled addons
   • Error messages from the console
   • Steps to reproduce the issue

Before reporting bugs, try repairing your installation and disabling all addons to rule out conflicts.