Chapter 8 — The First Round of Troubleshooting

First — On Debian 13, "Mostly Everything Just Works"

A blunt note up front. Right after first boot on Debian 13 (Trixie), it's increasingly common for none of the seven categories below to actually be broken on a given machine. The era of "install Linux on a laptop, and Wi-Fi / sound / suspend will definitely break at least one" is over.

We keep this chapter anyway, for two reasons.

Hardware varies. Newer chips, discrete GPUs, and unusual wireless modules still need a touch of work.
The craft of diagnosis — reading journalctl, inspecting lspci, handing logs to Claude — is the foundation you'll reuse for every later chapter.

So treat this chapter not as "the chapter you're stuck in now" but as "the chapter you open when you get stuck." If first boot brought up a desktop, the Wi-Fi connected, sound played, and Japanese input worked, you can skim Section 2 onward.

Break Down "It's Not Working"

When you feel "something is not working" right after install, don't panic — break it down. Check, in each of the following seven categories, whether things work or not.

Display (resolution, scaling, external monitor)
Wi-Fi (connects, speed, stability)
Bluetooth (mouse, keyboard, earphones)
Sound (built-in speakers, headphones, microphone)
Suspend / resume (close the lid and open it, power saving)
Japanese input (Fcitx5 + Mozc)
Peripherals (printer, webcam, USB devices)

On Debian 13 it's possible everything works on first boot. Even then, walking through the decomposition once is worth it — six months from now, when something does break, this is the muscle that rescues you.

Section 1 — Common Diagnostic Practice

Capture Logs and Hand Them Over

A strength of Linux is that everything that happens leaves a trace in the logs. There are three kinds of information you'll want to hand to Claude in trouble.

1. System logs.

journalctl -b -p err          # errors since this boot
                journalctl -b --since "10 min ago"   # the last 10 minutes

2. Hardware recognition state.

lspci -nnk                    # PCI devices and their drivers
                lsusb                         # USB devices
                dmesg | tail -50              # tail of kernel messages

3. The state of a specific service.

systemctl status <service-name>
                systemctl --failed            # list of failed services

Ask Claude (Template): A Common Troubleshooting Prompt

A template prompt that works for any kind of trouble.

On my Debian 13 [DE name], [symptom] is happening.

Machine: [maker / model] What I did just before: [the action]

Below is information about my environment:
$ uname -a
                [output]
                $ lspci -nnk | grep -A 2 -i [related keyword]
                [output]
                $ journalctl -b -p err
                [output]
                
Please list the three most likely causes in descending order of likelihood, with steps to verify each. Add a warning note for any destructive command.

Having this template raises the quality of Claude's answer significantly.

Section 2 — Display

Symptom: low resolution, blurry text

This is mostly about the GPU driver. Try the following.

# Confirm the current driver
                lspci -nnk | grep -A 2 VGA

                # Intel / AMD work with the standard drivers in most cases.
                # NVIDIA may need a separate package.

For a discrete NVIDIA GPU, install nvidia-driver from the non-free-firmware repository.

# Confirm contrib non-free non-free-firmware are in /etc/apt/sources.list
                cat /etc/apt/sources.list

                # Add them if needed (ask Claude for the exact format)
                sudo apt update
                sudo apt install nvidia-driver
                sudo reboot

Symptom: external monitor doesn't show

# Connected displays
                xrandr                        # X11
                gnome-randr                   # Wayland on GNOME (apt install if needed)

                # Resolution settings
                Settings → Display → Arrangement and resolution

Symptom: HiDPI (high resolution) makes the UI too small

GNOME: Settings → Display → Scale 125% or 150%
KDE Plasma: System Settings → Display and Monitor → Global scale
Xfce: takes a bit of effort. Ask Claude for the xfconf-query settings.

Section 3 — Wi-Fi and Network

Symptom: Wi-Fi doesn't connect at all

The Debian 13 netinst ISO bundles non-free firmware, so the case of "Wi-Fi never connected once since install" is much rarer than it used to be. If it does happen, suspect either a very new wireless chip or one whose firmware lives only in contrib.

# Identify the chip
                lspci -nnk | grep -A 2 -i net

                # Recognition state and firmware load history
                dmesg | grep -iE 'firmware|wifi|wlan'

Install the needed firmware package — firmware-iwlwifi (Intel), firmware-realtek, firmware-atheros, etc. Or pull firmware-linux-nonfree for the whole set.

sudo apt install firmware-linux firmware-linux-nonfree
                sudo reboot

Symptom: connects but slow / drops

The 2.4 GHz band may be congested. If a 5 GHz SSID is available, switch to it. Power saving can also misbehave.

# Power-saving state
                iw dev <interface-name> get power_save

Section 4 — Sound

Symptom: no sound

# Confirm sound devices
                pactl list sinks short

                # Mixer
                pavucontrol             # GUI mixer; apt install pavucontrol if needed

Common causes:

The default output is wrong (going to HDMI, or muted).
Headphone-detection auto-switching is misbehaving.
A Bluetooth device is being prioritized.

Symptom: microphone doesn't pick up

In pavucontrol's "Input Devices" tab, check the input level. Confirm it isn't muted and that gain isn't at 0.

Section 5 — Bluetooth

Symptom: Bluetooth devices aren't found

# Bluetooth service
                systemctl status bluetooth

                # If it isn't running
                sudo systemctl enable --now bluetooth

Some chips need firmware. Check with dmesg | grep -i bluetooth.

Section 6 — Suspend / Resume

Symptom: closing and reopening the lid doesn't bring it back

This is the trickiest issue on a laptop. The cause is a combination of kernel, drivers, and UEFI settings.

First things to try:

In BIOS / UEFI, switch between S3 sleep and Modern Standby (S0ix) (if the option exists).
Add mem_sleep_default=deep to the GRUB kernel parameters.

Ask Claude:

On my [model], resume from suspend fails. Symptom: after closing the lid and waiting more than 5 minutes, opening it leaves the screen black. Kernel: [output of uname -a]

Tell me the five most effective things to try, in order of effectiveness. Include the side effects of each step and how to revert.

Symptom: battery drains fast

# Power consumption state
                sudo apt install powertop
                sudo powertop

Try powertop --auto-tune for automatic optimization (note: some optimizations reduce usability, so be careful).

Section 7 — Japanese Input

Standard Configuration: Fcitx5 + Mozc

sudo apt install fcitx5 fcitx5-mozc fcitx5-config-qt

After install, run im-config -n fcitx5. Log out and back in.

Key bindings: the Hankaku/Zenkaku key, or Ctrl+Space (configurable in settings).

Symptom: Japanese input doesn't work in a specific app

Electron-based apps and Snap packages sometimes use a different input-method mechanism than the standard.

Ask Claude:

With Fcitx5 + Mozc, only [app name] won't accept Japanese input. Launch command and environment variables: [output of env | grep -i xim or GTK_IM_MODULE, etc.]

Tell me the environment variables or settings that need to be set on the app side.

Section 8 — Peripherals

Printers

Debian supports many printers via CUPS.

sudo apt install cups
                sudo systemctl enable --now cups

Open http://localhost:631 in a browser to add a printer. Canon, Epson, and Brother sometimes provide a separate driver for the Japanese market on the maker's site.

Webcam

# Recognition check
                v4l2-ctl --list-devices

                # Test
                sudo apt install cheese
                cheese

Section 9 — Priority Order for "Not Working"

When several issues show up at once, knock them down in this order.

Wi-Fi (without it you can't look anything up).
Display (you use it every day).
Sound (a problem in meetings).
Japanese input (affects most daily work).
Suspend / battery (gets in the way of constant use).
Bluetooth (alternatives are usually available).
Printer, webcam (handle when needed).

Don't try to solve everything at once. Once Wi-Fi works, you can knock down the rest in dialogue with Claude.

Ask Claude ⑥: Prioritize My List of Trouble

Right after install, the following issues are happening:

[symptom 1]

[symptom 2]

[symptom 3]

Tell me the order in which to knock them down, the expected time for each, and the very first step I should try.

Section 10 — Keep a Trouble-Resolution Log

For every issue you knock down, record it in a text file.

# My Debian Trouble-Resolution Log

                ## 2026-04-24 Wi-Fi wouldn't connect
                - Symptom: right after install, the Wi-Fi list was empty
                - Cause: firmware-iwlwifi was not installed
                - Fix: sudo apt install firmware-iwlwifi; sudo reboot
                - Reference: dialogue with Claude (saved at: [location])

                ## 2026-04-25 Black screen after closing and reopening the lid
                - Symptom: resume from suspend failed
                - Cause: Modern Standby vs. Linux compatibility
                - Fix: switched BIOS to "Linux" mode + added mem_sleep_default=deep to GRUB

This log will help you in the future. When the same issue comes back, when someone else asks you about a similar issue, when you reinstall.

Summary

What you did in this chapter:

Got the common diagnostic commands (journalctl, lspci, dmesg) under your fingers.
Covered the typical issues for display, Wi-Fi, sound, Bluetooth, suspend, Japanese input, and peripherals.
Established the practice of knocking them down by priority.
Built troubleshooting-log.md.

Where you are now:

A Debian environment usable day to day.
A personal log for when things stumble.

This closes Part 2 (Installation). In Part 3 (Chapters 9–12), we move into building the daily environment. Going deeper into the desktop environment, finalizing Japanese input, choosing daily-use applications, and managing config files — together with Claude.

The full series can be navigated from Learning Debian with Claude — All chapters. Comments and discussion go to the Facebook group: AISeed — Biodiversity, Food, AI and Life.