Proxmox Container Won't Start: Fixing Common LXC Errors

Diagnosing Container Startup Failures

LXC containers in Proxmox are lightweight and fast, but when they refuse to start, the error messages can be vague. The key to troubleshooting is checking the right logs and understanding the common failure modes. This guide covers the errors you are most likely to encounter and provides specific fixes for each one.

# First, try starting the container and capture the error
pct start 200

# Check the task log for details
# In the web UI: VM > Task History > click the failed task

# Check system logs for LXC errors
journalctl -u pve-container@200 -n 50

# Check the container's own log
cat /var/log/lxc/200.log

# Get container configuration
pct config 200

Error: Storage Not Available

The container's root filesystem or mount points reference storage that is not currently accessible.

# Check which storage the container uses
pct config 200 | grep rootfs
# rootfs: local-lvm:vm-200-disk-0,size=8G

# Verify the storage is available
pvesm status

# If the storage is an NFS mount, check connectivity
mount | grep nfs
showmount -e 192.168.1.100

# If using ZFS, check pool status
zpool status

# If storage was renamed or removed, update the container config
# Edit /etc/pve/lxc/200.conf
# Change the storage reference to match available storage

# If the disk volume is missing, check if it exists
lvs | grep vm-200
# or for ZFS:
zfs list | grep vm-200

Error: Container Is Locked

A lock left behind by a failed operation (backup, snapshot, migration) will prevent the container from starting.

# Check for locks
pct config 200 | grep lock

# Common lock types:
# lock: backup     - a backup was in progress
# lock: snapshot   - a snapshot operation was running
# lock: migrate    - migration was in progress

# Remove the lock (only if the operation is no longer running)
pct unlock 200

# Verify no backup or snapshot process is still active
ps aux | grep -E "vzdump|pct" | grep 200

# After unlocking, try starting again
pct start 200

Error: cgroup v2 Issues

Newer Proxmox versions use cgroup v2 (unified hierarchy) by default, which can cause issues with older container templates or certain applications inside containers.

# Check which cgroup version is in use
mount | grep cgroup
# cgroup2 on /sys/fs/cgroup type cgroup2 = cgroup v2

# If a container requires cgroup v1, you can enable hybrid mode
# WARNING: this is a system-wide change and requires reboot

# Edit kernel command line
nano /etc/default/grub
# Add to GRUB_CMDLINE_LINUX_DEFAULT:
# systemd.unified_cgroup_hierarchy=0

# Update GRUB and reboot
update-grub
reboot

# Alternatively, for specific containers, check if the issue is
# the container OS not supporting cgroup v2
# Use a newer template that supports cgroup v2

Error: AppArmor Deny

AppArmor security profiles can block certain container operations. This is especially common with containers that need access to special devices or kernel features.

# Check for AppArmor denials
dmesg | grep "apparmor.*DENIED"
journalctl | grep "apparmor.*DENIED" | tail -20

# Common AppArmor denials:
# - Mount operations inside the container
# - Access to /proc or /sys entries
# - Device node creation

# Solution 1: Use a custom AppArmor profile
# In /etc/pve/lxc/200.conf, add:
# lxc.apparmor.profile: unconfined
# WARNING: this disables AppArmor protection for the container

# Solution 2: Switch to a less restrictive profile
# lxc.apparmor.profile: lxc-default-with-nesting

# Solution 3: Enable nesting feature in Proxmox
pct set 200 --features nesting=1

# Restart the container after changes
pct start 200

Error: Bind Mount Permission Denied

Bind mounts allow containers to access host directories, but permission issues are common, especially with unprivileged containers.

# Check bind mount configuration
pct config 200 | grep mp

# Example:
# mp0: /mnt/data,mp=/data

# For unprivileged containers, the host directory must be
# owned by the mapped UID range

# Check container UID mapping
pct config 200 | grep -E "unprivileged|lxc.idmap"

# Default unprivileged mapping starts at UID 100000
# So container root (UID 0) maps to host UID 100000

# Fix permissions for unprivileged containers
chown -R 100000:100000 /mnt/data

# Or set ACLs to allow access
setfacl -R -m u:100000:rwx /mnt/data

# For privileged containers, normal host permissions apply
# Container root = host root
chown -R root:root /mnt/data

Unprivileged Container Restrictions

Unprivileged containers run with reduced privileges for security. Some operations that work in privileged containers will fail in unprivileged ones.

# Common unprivileged container limitations:
# - Cannot create device nodes (mknod)
# - Cannot mount most filesystem types
# - Cannot load kernel modules
# - Limited access to /proc and /sys

# If you need NFS mounts inside the container:
# In /etc/pve/lxc/200.conf:
# mp0: /mnt/nfs-share,mp=/mnt/nfs
# Mount NFS on the host and bind-mount into the container

# If the container needs to run Docker:
pct set 200 --features nesting=1,keyctl=1
# For unprivileged Docker, also add to /etc/pve/lxc/200.conf:
# lxc.apparmor.profile: unconfined

# If you must use a privileged container (understand the risks):
pct set 200 --unprivileged 0
# Note: this usually requires recreating the container

# Check if a container is privileged or unprivileged
pct config 200 | grep unprivileged

General Container Startup Checklist

When a container refuses to start, work through this checklist. If you manage many containers across nodes, ProxmoxR can provide a centralized view of container status and help identify patterns in failures.

• Check for locks with pct config and unlock if stale
• Verify storage is available and the rootfs volume exists
• Review /var/log/lxc/200.log for detailed error messages
• Check dmesg for AppArmor denials
• Verify bind mount permissions match the container's UID mapping
• Ensure the container template is compatible with the host's cgroup version
• Try starting with pct start 200 --debug for verbose output

Most container startup issues come down to storage availability, stale locks, or permission mismatches. Systematic troubleshooting using the logs and configuration checks above will resolve the vast majority of cases.