Troubleshooting

Symptom, likely cause, and what to do, for the problems people meet most.

On this page

Install and first boot
Devices and environments
Consoles
Content Hub and images
License and editions
AI Generator

Each table lists a symptom, its likely cause and what to do. Several of these are expected behavior rather than faults. If nothing here helps, collect a diagnostic bundle and contact support.

Install and first boot#

Symptom	Likely cause	What to do
A virtual machine device does not start, and the message says virtual machines need nested virtualization. The console banner shows the same	The hypervisor does not pass hardware virtualization through to the appliance. Routers and containers are not affected	Shut the appliance down. Set CPU type `host` (Proxmox VE) tick Virtualize Intel VT-x/EPT or AMD-V/RVI (VMware Workstation) or Enable Nested VT-x/AMD-V (VirtualBox), then start it again. Settings › Status shows Virtualization: Ready when it works
The console banner shows no address	No network card, or no DHCP on its network	Check the virtual machine has a network card on a network with DHCP
The banner's Status line says Platform not ready and names a step	The start-up check found a step that did not complete	Open Settings › Status and read Last start. If it does not clear, collect a diagnostic bundle in Settings › Diagnostics
The browser warns about the certificate	Expected: the appliance created its own certificate on first boot	Continue to the site
Create and sign in stays dimmed	The password has fewer than 12 characters, or the two entries differ	Use at least 12 characters and type the same password in both fields
Device consoles cannot be reached directly from the LAN	By design: console ports are closed on the appliance's firewall	Open consoles from the web interface
SSH to the appliance is refused	By design: the firewall allows only the web ports	Use the web interface, and your hypervisor's console for the virtual machine
The session drops after changing the network settings	Expected: the address your browser used has changed	Open the new address. If the new gateway cannot be reached, ONEP puts the previous settings back

Devices and environments#

Symptom	Likely cause	What to do
A start is refused with a message about devices at a time	You are at your edition's limit of devices running at once	Stop another device, or see Limits per edition
A device cannot be saved or started, and the message says its size is above your edition's maximum	The device has more CPU or memory than your edition's largest-device limit	Give the device less CPU or memory
A new environment cannot be created	You are at your edition's limit of saved environments	Delete an environment you no longer need
Environments are off after the appliance restarted	Expected: environments stay off after a restart	Start the ones you need
A link will not delete	Both devices on a link must be powered off first. A link to a cloud node is the exception	Power off both ends, then delete the link
The Delete button on an environment is dimmed	The environment is running or changing state	Power the environment off, then delete it
An environment you meant to keep behind NAT is on your LAN	Its cloud node is in bridge mode. The Add Device dialog starts with Bridge selected	Right-click the cloud node and choose Switch to NAT

Consoles#

Symptom	Likely cause	What to do
Another session took over this console	Only one session at a time can hold a console, and another browser tab or user opened it	Choose Take it back
This console is in use	Another session is connected to the device	Choose Connect anyway
No login prompt yet	The device may present its screen instead of a serial prompt	Choose Desktop
Reconnecting with an attempt count, or The console could not be opened	The connection to the device dropped or could not be made	Wait for the retries, or choose Reconnect now
<device> is powered off	The device is not running	Choose Power on
Connected with a black screen	A guest that is still booting shows a black screen for a moment	Wait; the screen appears when the guest draws it

Content Hub and images#

Symptom	Likely cause	What to do
A card shows Needs N GB RAM in place of Deploy	The appliance has too little memory for this card	Choose a smaller card, or give the appliance more memory
A card shows Runs slowly: N cores recommended	The appliance has fewer cores than the card recommends	You can still deploy; expect a slower environment
The first deploy of a card takes a long time	The first build downloads the card's parts from the vendor	Let it finish; later deploys reuse the build. Run one heavy job at a time
A Discover download is refused, and the message names a date	You have used this month's Discover downloads	Wait for that date, or use an image already in your library
A Content Hub deploy is refused, and the message names a date	Your edition limits deploys over a rolling period	Wait for that date. See Limits per edition
An import is refused with ONEP imports one environment at a time	Another import is still running	Try again when it finishes

License and editions#

Symptom	Likely cause	What to do
That is not a license file, or signature does not verify	Wrong file, or a file that was changed	Upload the `.lic` file you were sent, unedited
The appliance runs as Community after a license expired	The license ended and its grace period passed	Install the renewed license in Settings › Licensing
You expected the appliance to contact ONEP about its license	This release sends no license check-in: the license is checked locally against the signed file	Nothing to do. An isolated or offline appliance runs normally
You bought a license but have not received it	The license file is emailed, normally within one business day	If it has not arrived after one business day, write to hello@onep.io
The edition shown is not the one you bought	The license did not install	Install it again in Settings › Licensing; if it persists, write to support with your license ID
A feature says it is not available on your edition	Expected: your edition does not include it	See Limits per edition
Report a Problem says ONEP could not reach the report service	The appliance cannot reach ONEP support, for example on an isolated network	Choose Save report file and email the file to hello@onep.io
Report a Problem says Problem reporting is not set up on this appliance yet	This appliance has no way to deliver reports	Write to hello@onep.io, and attach a diagnostic bundle from Settings › Diagnostics
The Reset tab's actions cannot be pressed, and Backup & restore has no buttons	Expected: they are not available in this release	See Backups and restore

AI Generator#

Symptom	Likely cause	What to do
AI service is temporarily unavailable (model host not responding)	The model is not running or cannot be reached	Check Settings › AI and the ONEP Assistant row in Settings › Status, which reads Connected or Not connected
AI generator is busy with a count of requests ahead of you	Other requests are being built first	Wait the time shown and try again
The assistant understands English only	The description was not in English	Describe the network in English
I only build network topologies	The description did not look like a network request	Name devices and connections, for example a firewall between two PCs
That topology is larger than I can build	The request asks for more devices than one environment can hold	Ask for fewer devices
Prompt too long	The description is above the length limit	Shorten it
Generation is slow	A model on this appliance runs on the CPU unless a GPU is present	Wait, or use an external AI service in Settings › AI