WireGuard fails to start on Ubuntu 22.04 primarily due to syntax errors in the configuration file, missing kernel modules, or permission issues with the private key. Diagnosing the specific error via journalctl and validating the config structure usually resolves the startup failure without requiring system-wide network resets or dangerous deletions.
Identifying the Root Cause via Logs
When a systemd service like WireGuard fails to initialize, the most reliable diagnostic step is to examine the system logs rather than guessing at network configurations. The commandsudo systemctl status wg-quick@server (replacing server with your actual interface name) provides an immediate overview of the failure state. However, for detailed error messages, you should use journalctl -u wg-quick@server --no-pager -n 50. This command displays the last fifty lines of logs specifically for that service unit, excluding timestamps for easier reading.
Look for keywords such as "failed," "permission denied," or "syntax error." Common symptoms include the service entering a "failed" state immediately after boot or when manually triggered with sudo systemctl start wg-quick@server. If the log indicates that the module cannot be loaded, the issue lies within the kernel headers or secure boot settings. If it reports a configuration error, the problem is strictly within the .conf file structure. Avoid restarting SSH services or deleting configuration files unless explicitly instructed by a specific error message indicating corruption, as this can lock you out of remote management.
Validating the Configuration File Syntax
The vast majority of WireGuard startup failures on Ubuntu stem from malformed configuration files. The WireGuard configuration format is strict; even minor typos in section headers or missing brackets can prevent the daemon from parsing the settings. You must ensure that the file located at/etc/wireguard/wg0.conf (or your designated interface name) adheres to the correct structure.
A valid configuration requires three distinct sections: [Interface], [Peer], and potentially others depending on complexity. Each section header must be enclosed in square brackets and match exactly. Inside these sections, parameters are defined as Key = Value. Ensure there are no trailing spaces after values, as WireGuard’s parser is sensitive to whitespace. For example, a common mistake is adding comments inline with values or using incorrect capitalization for keys like PrivateKey versus privatekey.
To validate the syntax before attempting to restart the service, you can use the wg-quick tool in dry-run mode if available, or simply review the file with a text editor. Check that the PrivateKey under the [Interface] section is a valid base64-encoded string. Similarly, verify that all PublicKey entries in the [Peer] sections are correctly formatted. Incorrect keys will result in authentication failures, but malformed sections will cause immediate startup termination.
Checking Kernel Module and Secure Boot
Ubuntu 22.04 relies on the out-of-tree kernel module for WireGuard. If the module is not loaded, the service cannot bind to the network interface. You can check if the module is active by runninglsmod | grep wireguard. If this command returns no output, the module is not loaded. In many cases, loading the module manually with sudo modprobe wireguard can resolve temporary issues. If the command succeeds, attempt to start the service again.
However, on systems with Secure Boot enabled, unsigned kernel modules may be blocked by the Linux Security Module (LSM). If modprobe fails with a "Operation not permitted" or similar error, Secure Boot is likely the culprit. You have two options: disable Secure Boot in your BIOS/UEFI settings, or sign the WireGuard module. Disabling Secure Boot is the simpler path for most troubleshooting scenarios. Note that this setting is persistent across reboots until changed, so ensure you remember your BIOS password if applicable.
Additionally, ensure that the necessary build tools were present during the initial installation of the WireGuard package. On some minimal Ubuntu installations, missing dkms dependencies can prevent the module from compiling automatically. Installing linux-headers-generic and dkms ensures that future kernel updates do not break the WireGuard functionality.
Permissions and Key Ownership
Security best practices dictate that WireGuard private keys should only be readable by the root user. If the permissions on/etc/wireguard/wg0.conf are too open, the service may refuse to start to protect the key material. Check the file permissions using ls -l /etc/wireguard/wg0.conf. The expected output should show -rw------- owned by root:root. If other users have read access, correct this immediately with sudo chmod 600 /etc/wireguard/wg0.conf.
Conversely, if the file is unreadable by root, the service will also fail. Ensure ownership is correct with sudo chown root:root /etc/wireguard/wg0.conf. These permission checks are critical because they are often overlooked during manual edits using graphical text editors that might alter default ACLs.
For related network connectivity issues on Ubuntu VMs, see Ubuntu 22.04 VM on KVM/virt-manager Not Connecting to Internet. This resource helps distinguish between service-level failures and broader virtual machine network stack problems.
Restarting and Verifying the Service
Once you have addressed potential syntax errors, module loading issues, and permission constraints, proceed to restart the service. Usesudo systemctl restart wg-quick@server to apply changes. Immediately check the status with sudo systemctl status wg-quick@server. A successful start will show an "active (exited)" or "active (running)" state, depending on the systemd unit definition.
Verify that the interface is up by running ip link show wg0 (adjusting for your interface name). The state should be UP. Finally, test connectivity from a client device configured to connect to this server. If the connection succeeds, the troubleshooting process is complete. If it fails, revisit the logs for new errors, which may indicate firewall restrictions rather than service startup failures.
Frequently Asked Questions
Why does my WireGuard service show "failed" instead of "inactive"?
A "failed" state indicates that the service attempted to start but encountered a fatal error, such as a bad config file or missing module. An "inactive" state means the service is stopped and has not been recently attempted. Check the journal logs to identify the specific cause of the failure.
Can I use a GUI tool to edit WireGuard configs on Ubuntu?
While GUI tools exist, they are prone to introducing formatting errors that break the strict WireGuard syntax. It is safer to edit the .conf file directly using a terminal-based editor like nano or vim to ensure precise control over spacing and case sensitivity.
What if the WireGuard module loads but the interface doesn't appear?
If the module loads but no interface appears, check for duplicate configuration files or conflicting names. Ensure that the filename in /etc/wireguard/ matches the interface name referenced in your systemd command. Also, verify that no other network manager is trying to claim the same IP range.
Does disabling Secure Boot affect my system's security significantly?
Disabling Secure Boot allows unsigned kernel modules to load, which is necessary for WireGuard on some setups. While it reduces protection against low-level bootkits, the practical risk for most desktop and server users is minimal compared to the benefit of having a working VPN. Keep your system updated to mitigate other risks.
How do I know if my private key is valid?
A valid private key is a 44-character base64-encoded string. You can generate a new one using wg genkey and pipe it to a file. If you paste a key incorrectly, the service will fail to start. Always copy keys carefully, avoiding extra whitespace or line breaks.