The screen stays black when you plug in the dock
You close your laptop lid, plug in a USB-C dock, and expect the external monitor to wake up. Instead, you get a black screen or a stretched 1024x768 window. You wiggle the cable. You check the dock LEDs. Nothing changes. You are not alone. Display handshakes fail more often than people admit, especially when mixing laptop ports, docking stations, and Fedora's default compositor. The system sees the cable but refuses to send a picture.
What is actually happening under the hood
The display stack has three layers. The kernel detects the physical link. The DRM subsystem negotiates a timing mode. The compositor applies the layout and draws the pixels. If any step breaks, you see nothing. Think of it like a phone call. The kernel is the telephone line. The driver is the dial tone. The compositor is the person answering. If the line is dead, you never reach the person. If the dial tone is wrong, the call drops. If the person answers but speaks a different language, you get static. Fedora handles the line and dial tone automatically. The compositor decides what you actually see.
The kernel uses the Direct Rendering Manager and Kernel Mode Setting to talk to your graphics hardware. When you plug in a monitor, the hardware reads the EDID chip on the monitor. That chip tells the kernel what resolutions and refresh rates the screen supports. The kernel builds a list of valid modes. The compositor picks one and tells the hardware to start sending frames. If the EDID data is corrupted, the kernel falls back to a safe low resolution. If the compositor does not understand the new port, it keeps drawing only to the laptop screen.
Convention aside: Fedora defaults to Wayland on the GNOME session. Wayland changes how display configuration works. The old X11 tools do not talk directly to the Wayland compositor. You need to understand which protocol your session is running before you start typing commands. The compositor owns the display state. You cannot override it from outside the session.
How to detect and configure the display
Start with the GUI. Open Settings, click Displays, and look for the external output. GNOME usually saves the last active layout. If the GUI works, stop here. The graphical interface handles the compositor communication correctly. If the GUI shows the monitor but refuses to apply changes, or if you need to script the layout for a headless server or a kiosk, switch to the command line.
First, identify your active outputs. Run the query command to see what the system recognizes.
xrandr --query # Lists all connected outputs and their supported modes
Look for the external port identifier. It will usually be HDMI-1, DP-1, or DP-2. The built-in laptop screen is typically eDP-1. The word connected means the kernel sees the cable. The word disconnected means the handshake failed or the cable is loose. If the port shows connected but lists no modes, the EDID negotiation failed.
To enable the external monitor and place it to the right of your laptop screen, run the configuration command.
xrandr --output HDMI-1 --mode 1920x1080 --right-of eDP-1 # Turns on HDMI-1, sets resolution, and positions it relative to the laptop screen
Replace HDMI-1 with your actual port name. Use --left-of, --above, or --below to adjust the physical arrangement. The command applies immediately. If the screen goes black, wait ten seconds. X11 will revert the change automatically if the monitor cannot sustain the mode.
Some monitors report incorrect EDID data. The system only shows a few low resolutions. You can generate a custom timing string and inject it manually.
cvt 2560 1440 60 # Calculates VESA CVT timing parameters for 2560x1440 at 60Hz
Copy the output line. It will look like a long string of numbers and flags. Create the new mode and attach it to your port.
xrandr --newmode "2560x1440_60.00" 241.50 2560 2752 3024 3488 1440 1443 1448 1481 -hsync +vsync # Registers the custom timing string with the X server
xrandr --addmode HDMI-1 "2560x1440_60.00" # Attaches the new mode to the HDMI-1 output
xrandr --output HDMI-1 --mode "2560x1440_60.00" --right-of eDP-1 # Applies the custom mode and sets the layout
Persistence depends on your desktop environment. GNOME saves display layouts automatically. If you are on a minimal desktop or a tiling window manager, you need a startup script. Place the xrandr commands in ~/.config/autostart/ as a .desktop file, or append them to your window manager's configuration file. Do not edit files in /usr/lib/. Those files ship with packages and get overwritten on updates. Always put custom scripts in /etc/ or ~/.config/.
If your session is running Wayland, xrandr will fail silently or print an error. Wayland compositors handle display configuration internally. Use the GNOME Settings application or the wlr-randr tool if you are running Sway or Hyprland. The compositor owns the display state. You cannot override it from outside the session.
Reboot before you debug. Half the time the handshake fails because the dock powered up before the laptop finished initializing.
Verify the layout and refresh rate
Check the active configuration and refresh rate.
xrandr --query | grep -E "connected|current" # Filters the output to show only active ports and their current resolution
Look for the current line next to your external port. It should match the resolution you requested. If the refresh rate is wrong, add --rate 60 to the xrandr command. Some monitors default to 30Hz over USB-C adapters. The low refresh rate makes the cursor feel sluggish.
If the output shows 1920x1080 (normal) 60.00*, the asterisk means the system is actively using that mode. If you see 30.00 instead of 60.00, your cable or dock cannot handle the bandwidth. Switch to a direct HDMI connection or upgrade to a USB-C cable rated for 4K@60Hz.
Run journalctl -xe if the layout reverts after a few minutes. The x flag adds explanatory text and the e flag jumps to the end. Most sysadmins type journalctl -xeu <unit> muscle-memory style. Look for messages from gnome-shell or mutter. The compositor will log why it dropped the configuration.
Trust the package manager. Manual file edits drift, snapshots stay.
Common pitfalls and what the error looks like
The most common failure is a missing kernel module. The system sees the cable but cannot drive the display. Check the kernel ring buffer for DRM messages.
dmesg | grep -i drm # Shows kernel messages related to the Direct Rendering Manager
If you see failed to load firmware or no connector found, the driver is not initializing correctly. NVIDIA proprietary drivers require the akmod-nvidia package. The module must match the running kernel exactly. Run sudo dnf upgrade --refresh to ensure the kernel and drivers are aligned. Reboot after the upgrade. The display manager will load the new module on the next boot.
Another common issue is SELinux blocking a custom script. If you placed a display script in an unusual directory, the security context might prevent execution. Check the audit log for denials.
sudo ausearch -m avc -ts recent # Shows recent SELinux access vector cache denials
If you see a denial related to your script, restore the default context.
sudo restorecon -v /path/to/your/script # Resets the SELinux context to the default for that path
SELinux denials for standard display configuration are rare. They usually appear when users run display tools from cron jobs or systemd services without the correct context. Run display commands from your user session instead.
You may also encounter a black screen with this exact error in the journal:
mutter[1234]: XRandR: Failed to set output configuration: Invalid argument
The error means the compositor rejected the mode. The monitor does not support the requested resolution over the current cable. Drop to a lower resolution or check the cable rating. Do not force the mode with --force. Forcing a bad mode can leave you unable to see the desktop. Switch to a TTY with Ctrl+Alt+F3 and revert the configuration.
Read the actual error before guessing.
When to use which tool
Use GNOME Settings when you want a reliable, point-and-click configuration that persists across reboots. Use xrandr when you need to script a specific layout for a kiosk, a presentation, or a headless server. Use cvt and --newmode when the monitor reports incorrect EDID data and limits you to low resolutions. Use wlr-randr when you are running a Wayland compositor like Sway and need command-line control. Stick to the graphical interface for daily desktop use. The command line is for automation and troubleshooting.