Diagnosing xdg-open Failures When Opening URLs on Linux

Recognizable condition

When you run xdg-open with a URL or file path, the command returns a non‑zero exit status and no application launches. You may see only a brief error message or nothing at all, depending on the value of $XDG_UTILS_DEBUG_LEVEL.

Cause / diagnostic table

Possible cause	What to look for
Missing or incorrect MIME type association	xdg-mime query filetype returns "application/octet-stream" or an empty string.
Broken or missing .desktop file for the handler	The .desktop file referenced by xdg-mime query default is absent, lacks an Exec= line, or has invalid syntax.
Stale user‑specific mimeapps.list overriding system defaults	~/.config/mimeapps.list contains an entry that points to a non‑existent .desktop file.
Environment variables interfering (e.g., $BROWSER, $DESKTOP_SESSION)	Variables are set to a value that does not correspond to an installed application.
Debug level hiding useful output	$XDG_UTILS_DEBUG_LEVEL is set to a high value, suppressing informational messages.

Ordered checks

1. Run xdg-open --verbose <url> in a terminal (no special permissions needed). Capture the output; it shows which MIME type is being considered and which .desktop file is consulted.

2. Determine the MIME type of the target: xdg-mime query filetype <url>. If the result is unexpected or empty, note the MIME type.

3. Find the current default handler: xdg-mime query default <mime-type>. This returns the .desktop file name (e.g., firefox.desktop).

4. Locate that .desktop file: first check ~/.local/share/applications, then /usr/share/applications. Verify the file exists and is readable.

5. Inspect the Exec= line inside the .desktop file. It should contain a valid command, optionally with placeholders like %u for URLs. Look for typos, missing quotes, or references to non‑existent binaries.

6. Check for interfering environment variables: echo $BROWSER $DESKTOP_SESSION $XDG_UTILS_DEBUG_LEVEL. If any are set, note their values.

Fixes tied to findings

• MIME type unknown or incorrect – If xdg-mime query filetype returns an unexpected type, you can add or correct the association:

  # User‑scope (no root needed)
  xdg-mime install --novendor --mode user <mime-type-file>
  # Example: adding a custom type for .myapp files
  xdg-mime install --novendor --mode user myapp.xml
  

  After installing, repeat step 2 to confirm the MIME type resolves correctly.

• .desktop file missing or malformed – Reinstall the providing package (e.g., sudo apt reinstall firefox) or manually edit the file:

  • Ensure the file starts with [Desktop Entry].
  • Set Exec=/usr/bin/firefox %u (or the appropriate binary).
  • Make sure the file is marked executable: chmod +x /path/to/file.desktop (though not strictly required for xdg-open).

  If you edit a system‑wide file, you need root privileges; prefer editing the copy in ~/.local/share/applications to avoid affecting other users.

• Stale entry in mimeapps.list – Open ~/.config/mimeapps.list, locate the line that assigns the problematic MIME type to a non‑existent .desktop file, and either delete it or replace it with the correct handler. Save the file.

• Environment variable override – Unset or adjust the variable:

  # Temporarily for the current session
  unset BROWSER
  # Or set to preferred handler
  export BROWSER=firefox
  

  To make the change permanent, add the export line to your shell’s startup file (~/.bashrc or ~/.zshrc).

• Debug level hiding output – Lower the debug level:

  export XDG_UTILS_DEBUG_LEVEL=0
  

  Then rerun xdg-open --verbose to see the full trace.

Escalation criteria

If after completing the ordered checks and applying the relevant fix:

• The MIME type is correctly resolved,
• The referenced .desktop file exists with a valid Exec= line,
• No interfering environment variables remain, and
• xdg-open --verbose still returns a non‑zero exit code or fails to launch the application,

then collect the verbose output, the relevant mimeapps.list excerpt, and the .desktop file contents, and file a bug against the xdg-utils package of your desktop environment (e.g., ubuntu-bug xdg-utils on Debian/Ubuntu). Include the distribution name, desktop environment version, and the exact command you attempted.

Verification

After any change, run:

xdg-open --verbose <test-url>

Confirm that:

1. The expected application starts.
2. The command exits with status 0 (check with echo $?).
3. xdg-mime query default <mime-type> returns the corrected .desktop file name.
4. The .desktop file referenced by that output exists and contains a proper Exec= line.

If the test fails, repeat the ordered checks starting at step 1.

Limitations and practical tips

• User‑specific changes (~/.local/share/applications, ~/.config/mimeapps.list) affect only the invoking user; system‑wide fixes require root and may impact other accounts.
• Some desktop environments provide their own URL handlers that bypass xdg-open (e.g., GNOME’s gio open). If those work while xdg-open does not, the problem is isolated to the xdg-utils stack.
• Verbose output may contain the full URL you are trying to open; sanitize any sensitive information before sharing logs in public bug reports.
• Do not edit /usr/share/applications files directly unless you are reinstalling the owning package; manual edits can be overwritten on updates.