Proxmox LXC Container Won’t Start: Fixes

When a Proxmox LXC container refuses to start, the cause is almost always a corrupted container configuration, a storage or template issue, or a resource conflict on the host. The fix depends on the error message, but most cases are resolved by checking the container’s configuration file, verifying storage availability, and ensuring the host has enough free resources. Below is a systematic guide to diagnosing and fixing the most common reasons an LXC container fails to start.

Background: How LXC Containers Work in Proxmox

Proxmox VE uses Linux Containers (LXC) as its default container technology, which shares the host’s kernel and provides an isolated user space. Unlike virtual machines (VMs) that emulate hardware, LXC containers are lightweight and start by launching a single init process inside their own namespace. The container’s configuration is stored in /etc/pve/lxc/<CTID>.conf, where CTID is the container ID (e.g., 100). This file defines the container’s resources, network, storage, and startup options. When you press Start, Proxmox reads this file, mounts the container’s root filesystem, and runs the init process. Any misconfiguration, missing storage, or resource conflict can prevent the container from starting.

Common Causes and Their Fixes

1. Storage Not Available or Mount Failed

If the container’s root filesystem resides on a storage that is not mounted (e.g., an external USB drive, NFS share, or ZFS pool that didn’t mount after reboot), the container won’t start. Check the error message in the task log: it often says mount failed: No such file or directory or storage 'local-zfs' is not online.

• Go to Datacenter → Storage and verify the storage status is Active.
• If it’s inactive, try to mount it manually from the host shell: pvesm status to list storage, then pvesm mount <storage>.
• For NFS or CIFS shares, check network connectivity and credentials.
• If the storage is a ZFS pool, run zpool import if needed, then zpool status.

2. Corrupted or Incorrect Configuration File

Editing the container’s .conf file manually can introduce syntax errors or invalid values. Even a small mistake, like an invalid network bridge name, can cause the container to fail. The error might be parse error: invalid syntax or unknown configuration option.

1. Open the configuration file: nano /etc/pve/lxc/<CTID>.conf.
2. Look for obvious mistakes: misspelled keys, missing quotes, or values out of range.
3. Compare with a working container’s config if available.
4. If you’re unsure, back up the file and try removing recent changes.

3. Resource Conflicts or Host Overload

If the host is out of memory, disk space, or has too many processes, the container may fail to start. Proxmox will log Cannot allocate memory or No space left on device.

• Check free RAM with free -h on the host.
• Check disk space with df -h.
• If using ZFS, check for ARC pressure: arcstat or zpool iostat.
• Reduce the container’s memory limit in its options if the host is low.
• Stop unused VMs or containers to free resources.

4. Missing or Broken Template or Rootfs

If the container’s rootfs is missing or corrupted, the start will fail. This can happen if you deleted the template by accident or if the disk image is damaged.

• Check the container’s hardware tab to see the rootfs path.
• On the host, verify the path exists: ls -la /var/lib/vz/images/<CTID>/ or the appropriate storage path.
• If the file is missing, you may need to restore from backup or recreate the container.
• If it’s corrupted, try fsck on the disk image (if it’s a raw or qcow2 file) but be careful with ZFS.

5. Network Configuration Errors

A bad network configuration (e.g., bridge not existing, wrong IP) can prevent the container from starting because Proxmox tries to attach the container to a bridge that doesn’t exist.

• Check the host’s network bridges: brctl show or ip link show.
• In the container’s .conf, verify net0 line references an existing bridge like vmbr0.
• If the bridge is missing, recreate it in Datacenter → Network.

6. LXC Features or AppArmor Issues

Some containers require specific features like nesting, FUSE, or keyctl. If these are not enabled, the container may fail. Also, AppArmor profiles can block certain operations.

• Edit the container’s options and enable Features like nesting=1 if needed.
• Check AppArmor status: aa-status and ensure the container’s profile is not in complain mode.
• If you see Permission denied errors, try disabling AppArmor for the container (not recommended for production).

7. Locked Container or Stale PID

If Proxmox crashed or a previous start didn’t finish, the container might remain locked. The error might say can't lock file '/var/lock/lxc/<CTID>'.

1. Check for running processes: ps aux | grep lxc.
2. If none, remove the lock file: rm -f /var/lock/lxc/<CTID> (be careful).
3. Alternatively, reboot the host to clear stale locks.

How to Diagnose the Exact Problem

Proxmox gives you a task log when you try to start a container. This log is the most valuable diagnostic tool. To see it:

1. In the web interface, select the container, go to Tasks in the left sidebar, and click the most recent start task.
2. Read the output carefully. Look for lines with ERROR or WARN.
3. If the log is not detailed enough, run pct start <CTID> from the host shell to see the error directly in the terminal.

Common error messages and their meanings:

• lxc-start: ... No such file or directory – usually a missing rootfs or configuration file.
• lxc-start: ... Permission denied – often AppArmor or file permission issues.
• lxc-start: ... Invalid argument – configuration value out of range.
• lxc-start: ... Resource temporarily unavailable – too many processes or memory.

Step-by-Step Fix Workflow

If you’re not sure where to start, follow this order:

1. Run pct start <CTID> from the host shell and note the error.
2. Check storage status: pvesm status.
3. Verify the container’s config file for errors.
4. Check host resources: free -h, df -h.
5. Review the task log in the web UI for clues.
6. If the container was working before, think about recent changes (updates, config edits, hardware changes).
7. As a last resort, restore from a backup.

Prevention and Best Practices

To avoid future issues, follow these practices:

• Always back up your containers before making config changes.
• Use Proxmox’s built-in backup feature (vzdump) regularly.
• Keep the host and containers updated, but test updates in a staging environment first.
• Monitor disk space and memory usage on the host.
• Use stable storage (ZFS or LVM) instead of external USB drives for production containers.
• Document any manual changes to container configs.

Frequently Asked Questions

Why does my LXC container show “locked” and won’t start?

This usually happens after an unclean shutdown or a failed start. Remove the lock file with rm -f /var/lock/lxc/<CTID> after confirming no container processes are running. If it persists, reboot the host.

Can I start an LXC container from the command line?

Yes, use pct start <CTID> from the host shell. This gives you immediate error output that may be more detailed than the web interface.

What does “TASK ERROR: storage ‘local’ is not online” mean?

It means the storage where the container’s disk resides is not mounted or accessible. Check the storage status in the web UI and mount it if necessary. For NFS/CIFS, verify network connectivity.

How do I fix a container that has a corrupted rootfs?

If the rootfs is corrupted, you can try repairing it with fsck on the disk image (if it’s a raw or qcow2 file), but this is risky. The safest option is to restore from a backup or recreate the container and reinstall the software.

Why does my container fail with “Permission denied”?

This is often due to AppArmor or file permission issues. Check the container’s features and ensure the rootfs files are owned by root. You can also try disabling AppArmor for the container temporarily to test.

Can a full host disk prevent a container from starting?

Yes, if the host disk is full, the container may not start because it cannot write to its rootfs or create necessary lock files. Free up space by removing old backups or logs, then try again.

Related

• Data Breaches That Shook the World
• Disable Google Assistant: Turn It Off on Android & Home
• Resin vs FDM Printers for Miniatures: Detail, Durability, Cost