SAYLOR Recover a Linux display after an NVIDIA driver, kernel, cable, input, display-manager, or GPU-selection failure while preserving a text-console path.
The result you're building
A restored graphical display using the correct cable/input, detected GPU, bound kernel module, compatible NVIDIA package/kernel combination, and working display manager, with a preserved text-console and known-good kernel rollback path.
Use this guide when
- A monitor reports no signal after reboot, kernel/driver update, cable move, or GPU change.
- Linux boots but only one display, low resolution, or software rendering is available.
Do not use it as a substitute for
- Do not repeatedly install
.runand repository drivers over each other. - Do not remove kernels or drivers until a TTY/SSH/recovery path is confirmed.
Before you change anything
- Collect the items below first. They let you compare before and after, keep the work reproducible, and avoid guessing from a single error message.
- Physical connection map and monitor input selection.
- GPU from
lspci -nnk, bound driver, kernel version, and Secure Boot state. - Installed NVIDIA packages, DKMS status, and
nvidia-smiresult. - Display-manager status, kernel log, and session type.
Understand the system before fixing it
No signal occurs before desktop configuration
If firmware/boot logo never appears on the connected port, test power, input, cable, port, and GPU seating before changing Linux.
Installed module and bound module are different questions
A package can be installed while nouveau, vfio, or no driver owns the GPU. lspci -nnk and kernel logs show the actual binding.
Kernel and NVIDIA module must match
DKMS/module packages must exist for the running kernel; Secure Boot may block an unsigned module.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means | ||
|---|---|---|---|---|---|
| No firmware image on any port | Hardware/path | Power cycle, correct input, known-good cable/port/display | Linux driver changes cannot fix pre-boot absence. | ||
GPU absent in lspci | PCI/power/hardware | Power off; reseat and verify PCIe power/slot | OS cannot bind a device it cannot enumerate. | ||
| GPU present; no kernel driver in use | Module | `lspci -nnk; journalctl -k -b \ | grep -iE 'nvidia\ | nouveau'` | Missing, blocked, unsigned, or failed module. |
nvidia-smi works; desktop absent | Display manager/session | systemctl status display-manager and logs | Driver is alive; fix compositor, Xorg/Wayland, or monitor routing. |
Step-by-step procedure
Work in order. Record the output after each step. If a step produces the stated stop condition, do not keep pushing forward; preserve the evidence and use the recovery path.
Step 01 — Prove the physical signal path
Why: Software work is wasted if the monitor watches the wrong input or cable/port is bad.
Do: Test one monitor, one known-good cable, one GPU port, and correct input; check firmware output.
Read the result: Firmware visible means hardware can produce signal; no firmware keeps investigation physical.
Next: Connect monitors to the discrete GPU, not an inactive motherboard port.
Step 02 — Secure a text recovery path
Why: Graphical restarts can strand the operator.
Do: Use Ctrl-Alt-F3, SSH, or recovery mode and confirm sudo before package changes.
uname -r
systemctl get-default
ls /boot/vmlinuz-* | sortRead the result: A stable TTY proves the system is booting beyond firmware.
Next: Record running and previously known-good kernels.
Step 03 — Identify GPU and actual driver binding
Why: Package names do not prove module use.
Do: Inspect PCI device, kernel driver, modules, Secure Boot, and kernel messages.
lspci -nnk | grep -A4 -E 'VGA|3D|Display'
mokutil --sb-state
lsmod | grep -E 'nvidia|nouveau'
nvidia-smiRead the result: NVIDIA bound plus working nvidia-smi shifts focus to display manager; no binding shifts to module/package branch.
Next: Do not blacklist drivers until evidence identifies a conflict.
Step 04 — Check module availability for the running kernel
Why: A kernel update can boot without a matching NVIDIA module.
Do: Inspect installed packages, DKMS or prebuilt module status, and modinfo for the running kernel.
ubuntu-drivers devices
dkms status
modinfo nvidia | head
dpkg -l | grep -E 'nvidia-driver|linux-modules-nvidia'Read the result: Module-not-found requires the supported Ubuntu driver/module package; signature rejection requires Secure Boot enrollment/signing resolution.
Next: Prefer Ubuntu packaged drivers and one installation method.
Step 05 — Restore the narrow software layer
Why: Purging everything can remove the only working fallback.
Do: Boot the known-good kernel if it has a working module, or install the Ubuntu-recommended driver and matching kernel modules; reboot once.
Read the result: After reboot the kernel driver must be nvidia and nvidia-smi must report the GPU.
Next: Then inspect the display manager only if screen remains blank.
Step 06 — Verify desktop and every output
Why: A working console or nvidia-smi is not the user's end result.
Do: Check display manager, session, connectors, resolution, and both monitors one at a time then together.
Read the result: No new Xid/module errors and stable modes complete recovery.
Next: Keep the previous kernel until several successful boots.
Worked example
nvidia-smi cannot communicate.Evidence collected
- Firmware appears on the monitor, proving cable/port path.
- GPU is present in
lspci, but noKernel driver in useis shown. - Running kernel has no matching installed NVIDIA module package.
- Display manager failures are downstream of missing GPU driver.
Decision: The running kernel/driver module set is incomplete, not a monitor setting problem.
Actions taken
- Booted the prior kernel from GRUB and confirmed NVIDIA binding.
- Installed the supported matching Ubuntu NVIDIA module/driver package for the current kernel.
- Rebooted, verified
nvidia-smi, display manager, and both connectors.
lspci shows nvidia bound; nvidia-smi works; journal has no new NVIDIA Xid/module errors.Why this example matters: The rollback kernel restored service before making the package set coherent.
Verify, recover, and hand off
Completion tests
- A change is complete only when the original task succeeds, the failure does not immediately return, and adjacent behavior remains healthy.
- Firmware and Ubuntu display appear on intended GPU port.
lspci -nnkshows the expected driver bound.nvidia-smireports GPU/driver without communication error.- Display manager is active and native modes are available.
- Two cold boots succeed; previous kernel remains as fallback.
Rollback or safe recovery
- Select the known-good kernel from GRUB Advanced Options.
- Restore the prior Ubuntu driver package version only through the package manager.
- If graphical login fails, set multi-user target temporarily from TTY and preserve logs.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| Black screen with movable cursor | Driver may work; compositor/session fails. | Inspect display-manager and user-session logs. |
| Module signature rejected | Secure Boot does not trust module. | Enroll/sign via supported Ubuntu flow or use signed prebuilt modules. |
| nouveau bound instead of nvidia | NVIDIA module unavailable/failed or initramfs policy. | Fix installed module first; rebuild initramfs only with documented need. |
| One port works, another never does | Connector/cable/mode or GPU hardware path. | Swap cable/monitor/port and inspect connector state before driver reinstall. |
Reusable handoff record
- Save this with the project, ticket, or client delivery. It turns the work into a repeatable result instead of a one-time guess.
- Physical path and firmware test.
- Kernel/GPU/driver/Secure Boot/package evidence.
- Known-good kernel and recovery access.
- Exact package or configuration change.
- Cold-boot, multi-monitor,
nvidia-smi, and log verification.
Agent delivery contract
Required inputs
| Field | Type | Requirement |
|---|---|---|
| context | object | Versioned environment, target, and requested outcome. |
| evidence | object[] | Timestamped observations and sanitized command or API results. |
| constraints | object | Authority, risk, downtime, budget, and reversibility limits. |
| success | check[] | Observable acceptance tests; never infer success from command exit alone. |
Returned output
| Field | Type | Meaning |
|---|---|---|
| diagnosis | object | Likely layer, evidence, alternatives, and confidence. |
| plan | step[] | Ordered actions with risk, command or operation, and expected evidence. |
| verification | check[] | Pass/fail checks that prove the requested outcome. |
| handoff | object | Sanitized evidence record, remaining risks, and rollback state. |
Agent refusal and escalation rules
- Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
- Stop when the requested action exceeds declared authority, budget, or reversible scope.
- Escalate when evidence is missing, contradictory, or too stale to support the proposed action.
Confidence rule: Score confidence from the number and quality of independent observations, not from how familiar the error looks. Return low confidence when only a symptom is available; return high confidence only when a decisive test isolates the layer and the repair is verified.
Official reference starting points