Ubuntu 22.04 LTS Netplan Apply Breaks Network After YAML Change

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

After editing netplan files, network connectivity drops immediately following netplan apply. Remote SSH sessions disconnect and server workloads lose external and internal routing.

Environment & Reproduction

Ubuntu 22.04 LTS server uses systemd-networkd renderer with static addressing. Reproduce by introducing YAML syntax or interface-name mismatch and applying configuration without try rollback.

Root Cause Analysis

Netplan consumes strict YAML. Small indentation or key-name mistakes produce parse or runtime errors, while wrong interface mapping applies valid config to non-existent NIC identifiers.

Quick Triage

Use local console or out-of-band access, restore last known-good YAML, and run netplan generate before apply. Never rely solely on remote shell for first-time network edits.

Step-by-Step Diagnosis

Validate syntax, check generated backend config, and inspect networkd logs for failed units or DHCP/static conflict. Confirm interface names against actual kernel device names.

Solution – Primary Fix

Correct YAML indentation, renderer settings, and interface match keys; use netplan try first, then commit. This prevents lockout by automatically reverting failed network changes.

Solution – Alternative Approaches

Split configurations into separate files for bonds/VLANs, use cloud-init network config where appropriate, or temporarily assign emergency IP with ip command for recovery.

Verification & Acceptance Criteria

Interface receives correct addresses, default route is present, DNS resolution works, and reconnect tests from a remote management jump host succeed.

Rollback Plan

Restore previous YAML from version control or backup, run netplan generate and apply, then verify route and DNS baseline before retrying planned modifications.

Prevention & Hardening

Enforce YAML linting in CI, keep netplan files under git, and require netplan try during change windows for all production Ubuntu 22.04 hosts.

Related Errors & Cross-Refs

Often appears with systemd-networkd service failures, cloud-init overwriting static definitions, and incorrect predictable interface names after VM hardware changes.

Related tutorial: View the step-by-step tutorial for Ubuntu 22.04 LTS.

View all Ubuntu 22.04 LTS tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Consult netplan.io documentation, Ubuntu Server networking guide, and man pages for netplan(5), ip(8), and systemd-networkd.service(8).