Troubleshooting

Help Konqi catch some bugs!

Sometimes things stop working the way you expect them to work. An app crashes or refuses to launch. Your screen turns black. Your favorite widget is broken.

One thing is for sure: what's happening isn't what you were expecting. It's an issue!

Issues vs bugs

Not all issues are bugs. What's the difference?

• An issue is simply when you notice something not behaving the way you expect it to work.
• A bug is when the software doesn't work the way the developers expect it to work.

Bugs can usually be fixed by software developers. But many issues can only be fixed by you.

Your job is to determine what's causing your issue, and whether it's a bug suitable for reporting to the developers. Follow these steps to figure it out!

Is your expectation reasonable?

KDE's software is provided for free with no warranty, having been developed by a combination of volunteers and paid developers working on what their employers sponsored. So it's wise to keep your expectations reasonable.

Here are some examples of unreasonable expectations:

• My 14 year-old computer should perform at top speed when running the latest software with a nearly full hard disk.
• If I intentionally disable safety features, the system should still prevent me from ever losing data.

Whereas these are reasonable expectations:

• When I launch a KDE app, it shouldn't crash.
• This app's built-in customization options should all work.

If your expectations are reasonable because they match what the software has clearly been designed to do, move on.

What makes it happen?

The next step is to establish reproducibility — a set of steps you can perform to make the issue happen every time you do it.

Without this, the issue's cause will remain a mystery. There's almost no chance of either you resolving it, or developers fixing it.

Here are some ideas for narrowing down the cause:

Have you tried turning it off and back on again?

Many issues are transient and will go away after you restart the affected app or computer. Try that.

Is it just your user account?

Create a new user account on the same computer. Log into the new user account and don't make any changes beyond what's needed to encounter the issue. See if it still happens.

If the issue doesn't happen in the new user account, look into any customizations you've made in your normal user account that might be triggering the issue. For example:

• Heavily customized Plasma panel or theming setup
• Files stored on on network locations or external disks
• Multiple Activities or Virtual Desktops

What changed recently?

Did the issue begin happening after something changed? If so, what changed? For example:

• Upgrading to a newer version of the software
• Adding, removing, or replacing a connected device or hardware component
• Installing a new piece of software, especially a technical development package
• Customizing any settings
• Moving a laptop to a different Wi-Fi network, time zone, or country
• Setting up any new network mounts

What's special about your computer?

Issues can be caused by differences between the hardware characteristics of your computer compared to others. For example:

• Custom environment variables set in /etc/environment
• Using complex multiplexing hardware, such as docks, KVMs, multiple screens, or external audio cards
• Using Bluetooth audio devices or NVIDIA GPUs

Try simplifying your setup and see if the issue still happens.

Are there any errors in the log files?

If an application isn't launching or running properly, run it in a terminal window.

If the system is exhibiting issues right after login, scan through logs from the current boot using journalctl --boot 0, or the previous one using journalctl --boot -1.

If the issue involves entire system freezes or visual glitches, look through the kernel log using sudo dmesg.

Out of ideas?

If you haven't managed to identify what's triggering the issue, ask for help at https://discuss.kde.org/c/help/6.

You found the cause!

At this point you know the issue is real, and you you can make it happen at will.

Is it something I did?

Now ask yourself: "Is the issue caused by something I changed that's reversible by me?"

If it was, ask yourself whether it's something that really should be working.

For example, if the issue is only seen when a file is stored on a Samba server, that's something that definitely should be working! This may be a real bug, but now at least you know how to work around it in the meantime.

Is it already fixed?

Next ask: "Is it already fixed?"

If you're using a version of the software that's more than a year old, there's a decent chance the issue may have already been fixed.

Try upgrading to a more recent version. If no upgrades have been provided by your operating system, contact the people who created the operating system about the problem, not KDE.

If the issue still happens in a recent version, move on.

Is it happening to KDE software

If the issue is happening in an app or software library not made by KDE, there's nothing KDE can do about it. Contact the people who developed the troublesome component, not KDE.

Open a bug report

If you got to this point, the following should be true:

1. Something unexpected happens.
2. Your expectations about what should happen are reasonable.
3. You know exactly how to make it happen every time you try.
4. It happens in software made by KDE.
5. It happens in a recent version of the software.

If this is the case, it's time to open a bug report so KDE's developers can investigate the bug and hopefully fix it.

Here are some examples of the types of issues that can be reported:

• Crashes
• Broken functionality
• Anything that causes data loss
• Specific design or usability problems
• Translation problems and typos
• Accessibility issues
• Reasonable and realistic requests for specific new features (use the "wishlist" severity)

As a part of this process, make sure to:

• Preserve the buggy environment/situation for testing purposes, and not do anything that destroys your ability to reproduce the bug (such as reinstalling your OS or deleting all your settings).
• Be willing to correspond with KDE developers about the issue, potentially over an extended period of time.
• Be prepared to gather and report a lot of additional information.
• Be ready to potentially use a terminal program to execute command line debugging tools.

Good luck!