Desktop Troubleshooting

Desktop Troubleshooting

Start by identifying what changed and collecting output before changing configuration. A package update, a new device, a cable change, or a power event often narrows the cause. Commands in this guide only inspect the system unless they begin with doas.

Start with evidence

Record the operating-system version, the recent kernel messages, and the relevant hardware. Run these commands in a terminal and save the output when asking for help:

uname -a
dmesg | tail -100
pciconf -lv
kldstat

dmesg is especially useful immediately after connecting a device or reproducing a failure. Run it before and after the event and compare the new lines. Use pciconf -lv for graphics and network adapters, and kldstat to see loaded kernel modules.

For problems that appeared after a package change, first review installed updates with mport list updates and inspect the package with mport info package-name. See Desktop Software Management for package commands.

Graphical desktop problems

If the graphical login screen or desktop does not start, first determine whether the system itself is still usable. Switch to a text console if necessary, log in, and check free disk space and recent messages:

df -h
dmesg | tail -100
tail -100 /var/log/messages

A full filesystem can prevent a session from creating its configuration and log files. Do not delete files simply to create space; identify large, unneeded files first.

When starting X manually with startx, retry it from the console and read the final output. Xorg log files are commonly located at ~/.local/share/xorg/Xorg.0.log for a user session or /var/log/Xorg.0.log for a system-wide session. Look for lines marked (EE), then retain the surrounding lines; warnings alone do not necessarily indicate the cause.

For a graphical login manager, check its service status. On systems using the default mlogind display manager:

doas service mlogind status
doas service mlogind restart

Use the matching service name if you configured a different display manager. The Xorg and Desktop Environments guide covers the initial desktop and login-manager setup.

Services and applications

Check whether the service is enabled and whether it is currently running:

service -e
doas service service-name status

service -e lists enabled services. Replace service-name with the applicable service, such as cupsd for CUPS. If a service fails, inspect its recent messages before restarting it. For a user application, start it from a terminal so that any error message remains visible.

A package integrity check may help when an application reports a missing or altered file:

doas mport verify package-name
mport which /path/to/file

Do not remove packages or run mport autoremove as a first troubleshooting step. Review the package and any proposed removals first.

Hardware and drivers

Confirm that the operating system detects the device before changing desktop settings. For USB, storage, and printer devices:

usbconfig list
camcontrol devlist
dmesg | tail -100

Reconnect the device, try a known-good cable or port, then run the commands again. Record the device model and the new dmesg lines. See Desktop Peripherals for printers, scanners, Bluetooth, cameras, and removable storage; see Sound for audio devices.

For graphics or Wi-Fi hardware, include the matching section of pciconf -lv in a report. Driver support depends on the chipset, not only the computer or peripheral brand.

Network problems

Separate a link problem from a name-resolution problem. First inspect interfaces and test an IP address, then test a hostname:

ifconfig
ping -c 3 1.1.1.1
ping -c 3 www.midnightbsd.org

If the IP-address test succeeds but the hostname test fails, check /etc/resolv.conf and the DNS configuration guide. For wireless connections, use the Wi-Fi Setup guide to confirm the interface, association, and DHCP configuration.

Safe recovery steps

Save your work, then restart the smallest affected component first: an application, then its service, and only then the graphical session or system. A reboot is reasonable after a kernel, driver, or shared-library update, but it should not replace collecting the error output.

If an automatic graphical login loop prevents access to a terminal, use a text console to stop the display manager temporarily:

doas service mlogind stop

Substitute the display manager you actually use. This command does not disable it permanently; it lets you work from the console and inspect logs. Avoid editing /etc/rc.conf, loader settings, or Xorg configuration unless you understand the specific change and can undo it.

Reporting a problem

A useful report includes the MidnightBSD version, desktop environment, exact hardware model or chipset, the steps that reproduce the issue, and the complete error message. Include relevant output from uname -a, dmesg, pciconf -lv, and the affected service or application. Remove passwords, private host names, network addresses, and other sensitive data before publishing logs.