1. Identify state
Use zoneadm list -cv to see the current state: configured, installed, running, incomplete, shutting_down, etc.
Solaris · Zones Troubleshooting in Solaris
Solaris · Zones · Troubleshooting
Zones Troubleshooting in Solaris
Zones are powerful, but when something goes wrong you need a standard approach: check state, verify configuration, look at logs, fix resources and try again. This lesson covers typical zone and kernel zone problems and how to fix them in real environments.
Troubleshooting approach – zones and kernel zones
2. Verify configuration
Use zonecfg verify to catch missing network, datasets, pool or other resource problems.
3. Check logs & retry
Look into /var/log/zones, /var/adm/messages, and inside the zone (for kernel zones) before retrying boot/install.
Common problem areas
- Wrong or missing network interfaces.
- IPS repository / publisher issues during install.
- Insufficient memory/CPU for kernel zones.
- Kernel zone OS issues (inside the guest).
- Leftover 'incomplete' zones from failed attempts.
Typical issues & how to fix them
1. Quick view of zone states
First step: see which zone is failing and in what state (configured, installed, running, incomplete, etc.).
terminal — zones troubleshooting
solaris-lab[root@solaris ~]# zoneadm list -cv
ID NAME STATUS PATH BRAND IP
0 global running / solaris shared
- appzone installed /zones/appzone solaris excl
- kz-db01 incomplete /system/zones/kz-db01 solaris-kz excl
2. zonecfg verify – configuration errors
If a zone is in 'configured' or 'incomplete', run verify to see missing/invalid resources.
terminal — zones troubleshooting
solaris-lab[root@solaris ~]# zonecfg -z appzone verify
zonecfg:appzone: No such physical interface 'net999'
# Fix:
zonecfg:appzone> remove net
zonecfg:appzone> add net
zonecfg:appzone:net> set physical=net0
zonecfg:appzone:net> end
zonecfg:appzone> verify
zonecfg:appzone> commit
zonecfg:appzone> exit
3. zoneadm install – missing repository / IPS issues
Install failures often come from IPS repo problems or wrong publisher.
terminal — zones troubleshooting
solaris-lab[root@solaris ~]# zoneadm -z appzone install
A ZFS file system has been created for this zone.
...
pkg: unable to contact valid package repository.
zoneadm: zone 'appzone': WARNING: install failed
# Check IPS configuration:
[root@solaris ~]# pkg publisher
[root@solaris ~]# ping pkg.oracle.com
# Fix publisher and retry:
[root@solaris ~]# pkg set-publisher -g file:///export/localrepo solaris
[root@solaris ~]# zoneadm -z appzone install
4. Kernel zone fails to boot – insufficient memory/CPU
If caps are too high for available host resources, kernel zone may not boot.
terminal — zones troubleshooting
solaris-lab[root@solaris ~]# zoneadm -z kz-db01 boot
zoneadm: zone 'kz-db01': not enough memory to boot this zone
# Check configuration:
[root@solaris ~]# zonecfg -z kz-db01 info capped-memory
capped-memory:
physical: 64G
# If host has only 32G or heavily used, reduce cap:
[root@solaris ~]# zonecfg -z kz-db01
zonecfg:kz-db01> select capped-memory
zonecfg:kz-db01:capped-memory> set physical=16G
zonecfg:kz-db01:capped-memory> end
zonecfg:kz-db01> commit
zonecfg:kz-db01> exit
# Retry boot:
[root@solaris ~]# zoneadm -z kz-db01 boot
5. zlogin fails – zone not ready or console in use
If you can’t log in, check zone state and use -C carefully.
terminal — zones troubleshooting
solaris-lab[root@solaris ~]# zlogin appzone
zlogin: cannot connect to zone appzone; zone is down
# Check status:
[root@solaris ~]# zoneadm list -cv
ID NAME STATUS PATH BRAND IP
0 global running / solaris shared
- appzone installed /zones/appzone solaris excl
# Boot the zone:
[root@solaris ~]# zoneadm -z appzone boot
# Now console:
[root@solaris ~]# zlogin -C appzone
[Connected to zone 'appzone' console]
6. Kernel zone boot failures – check logs
If a kernel zone fails during OS boot, use console and logs inside the zone.
terminal — zones troubleshooting
solaris-lab[root@solaris ~]# zlogin -C kz-db01
[Connected to zone 'kz-db01' console]
...
panic[cpu0]: some kernel error
...
# After investigating, you may need to boot single-user inside the kernel zone,
# or roll back BE within the zone (like a normal Solaris system).
7. Clean up 'incomplete' zone
Sometimes a failed install leaves a zone in incomplete state. Clean and recreate if needed.
terminal — zones troubleshooting
solaris-lab[root@solaris ~]# zoneadm list -cv
ID NAME STATUS PATH BRAND IP
0 global running / solaris shared
- kz-db02 incomplete /system/zones/kz-db02 solaris-kz excl
[root@solaris ~]# zoneadm -z kz-db02 uninstall -F
[root@solaris ~]# zonecfg -z kz-db02 delete -F
8. Where to look for zone-related logs on global zone
Zone install/boot messages often appear in these logs.
terminal — zones troubleshooting
solaris-lab[root@solaris ~]# tail -100 /var/adm/messages | grep -i zone
[root@solaris ~]# ls /var/log/zones
appzone.install.log
kz-db01.console.log
kz-db01.install.log
Troubleshooting checklist – zones & kernel zones
- Always start with
zoneadm list -cv. - If config-related:
zonecfg -z <zone> verify. - If install-related: check IPS (
pkg publisher, network, repo availability). - If boot-related: check logs, resources and for kernel zones, treat them like mini-Solaris systems (BEs, SMF, etc.).
- Clean up failed/incomplete zones before retrying, to avoid confusion.
With a consistent checklist, even complex zone and kernel zone issues become manageable instead of scary.