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

​
General troubleshooting

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.
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
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

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.
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.).
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
 */
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

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.
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

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.
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

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.
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

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.
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
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us