You double-click a PDF and it opens in the text editor instead of the document viewer
Or you installed a new image viewer via Flatpak, but clicking a photo still launches the old default. GNOME remembers your choices, but sometimes the association breaks, or a new application needs to be registered as the handler for a specific file type. The desktop environment relies on MIME types and desktop entry files to decide which program launches when you open a file. When that mapping is missing or wrong, you have to fix it manually.
What's actually happening
GNOME uses a system called MIME types to identify files. A MIME type is a standardized string like application/pdf or image/png. Every application installed on your system registers itself with a .desktop file. This file tells the system what the app can do and which MIME types it supports. When you open a file, the desktop environment looks up the file's MIME type, checks which applications claim to handle that type, and picks the default. If no default is set, it asks you. If the default points to an app that no longer exists, or if a new app isn't registered correctly, the association fails. You can override these choices using the xdg-mime command, which updates the user configuration database.
MIME types come in two flavors. Standard types like application/pdf are defined by IANA and recognized by the system. Extension-based types like application/x-extension-txt are generated dynamically when the system sees a file extension that does not have a standard mapping. If you set a default for application/x-extension-txt, you are only fixing .txt files. If the system detects the content is actually text/plain, the association might not apply. Always prefer standard MIME types when possible. The xdg-mime query filetype command reveals the type the system currently assigns to a file.
Applications register themselves via .desktop files located in /usr/share/applications/ for system-wide installs or ~/.local/share/applications/ for user-local installs. The filename of the desktop entry is what you use with xdg-mime. For example, the GNOME Text Editor uses org.gnome.TextEditor.desktop. If you install an app via Flatpak, the desktop file is exported to /usr/share/applications/ or /var/lib/flatpak/exports/share/applications/. The filename usually matches the Flatpak ID. Fedora ships many apps as Flatpaks by default. You must use the full ID as the desktop file name. Using a shortened name like gimp.desktop for a Flatpak-installed GIMP will fail because the file does not exist.
Run xdg-mime query before you set. Blindly overwriting associations breaks workflows you didn't know you relied on.
The fix
Here's how to check the current default for a MIME type. This command reads the user configuration and prints the desktop file associated with the type.
# Check which app is currently set as the default for PDFs.
# This reads the user's mimeapps.list configuration.
xdg-mime query default application/pdf
Here's how to find the MIME type for a file if you don't know it. This is essential when dealing with obscure extensions or when the system generates an extension-based type.
# Find the MIME type for a specific file extension.
# This is useful when you don't know the type string.
xdg-mime query filetype /path/to/document.docx
Here's how to list desktop files to find the correct name for an application. You need the exact filename to set the default.
# List all desktop files to find the correct name.
# Filter by name to narrow down the search.
ls /usr/share/applications/ | grep -i evince
Here's how to set the default application. The command updates ~/.config/mimeapps.list with the new association.
# Set the default application for PDF files.
# The first argument is the .desktop file of the app.
# The second argument is the MIME type to associate.
xdg-mime default org.gnome.Evince.desktop application/pdf
The configuration is stored in ~/.config/mimeapps.list. This file has sections like [Default Applications] and [Added Associations]. The xdg-mime command manages this file automatically. Manual edits are possible but risky. The format requires specific syntax. If you break the syntax, the desktop environment may ignore the file. Trust the tool to write the file.
Check the desktop file name twice. A typo in the filename creates a dead link in the configuration.
Verify it worked
Here's how to confirm the association is active. The output must match the desktop file you just set.
# Verify the new association is active.
# The output should print the desktop file you just set.
xdg-mime query default application/pdf
If the output matches, click a file of that type in the file manager. It should open in the new application. If it does not, the file manager might be caching the old association. Restart the file manager or log out and back in.
Flatpak apps use their full ID as the desktop file name. Guessing the short name will fail.
Common pitfalls and what the error looks like
If you type a desktop file name that doesn't exist, xdg-mime might silently fail or update the config with a broken reference. The symptom is that clicking the file does nothing, or it falls back to the system default. The command may print an error to stderr.
xdg-mime: application not found: fake-app.desktop
This error means the .desktop file is not in the search path. Check /usr/share/applications/ and ~/.local/share/applications/. If you installed the app via Flatpak, ensure the desktop file is exported. Sometimes you need to run flatpak update or restart the session for the desktop file to appear.
Another common issue is the conflict between native apps and Flatpak apps. Fedora Workstation encourages Flatpaks. If you set a native app as the default, but a Flatpak app also handles the type, the xdg-desktop-portal might intercept the request. The portal manages associations for sandboxed apps. If the portal is misconfigured, the default might not apply. Check the journal for portal errors.
# Check for portal errors related to MIME handling.
# Look for lines mentioning xdg-desktop-portal.
journalctl -xeu xdg-desktop-portal
If the associations are chaotic, the mimeapps.list file might be corrupted. You can reset it by removing the file. The system will regenerate it with defaults on the next interaction.
# Reset all user MIME associations.
# This deletes the custom configuration file.
# The system will recreate it with defaults.
rm ~/.config/mimeapps.list
Reset the config file if the associations are chaotic. A fresh mimeapps.list is faster than hunting down every broken entry.
When to use this vs alternatives
Use xdg-mime when you need to set defaults from the terminal or script the configuration. Use the GNOME "Default Applications" settings panel when you prefer a graphical interface and are configuring common types like web browser or mail client. Use gsettings when you are adjusting GNOME-specific preferences that don't map to MIME types, such as the default web browser URI scheme. Use flatpak override when a sandboxed application cannot access the host's default handlers and you need to force a portal association. Stay on the GUI for one-off changes. Use the terminal for reproducible setups or when the GUI is unresponsive.