Skip to main content

​
Overview

This guide covers the most common operational issues encountered in Polystack Compute environments. Each section provides the diagnostic commands, root cause analysis, and resolution steps needed to restore normal operation.
Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.
Prerequisites
  • Administrator credentials sourced (source openrc.sh)
  • openstack CLI installed and configured
  • SSH access to compute nodes for log inspection when needed

​
Common Issues

Cause: The scheduler placed the instance on a host but the Compute Agent failed to complete provisioning. Common causes include image download failure, networking misconfiguration, or storage attachment failure.Diagnosis:
Check instance event log
Identify the target host
Check Compute Agent logs on the target host (via the deployment console terminal)
Common causes and resolutions:
If the instance is permanently stuck, force-delete it with openstack server delete --force <instance-id> and re-launch on a healthy host. Verify the target host is up and enabled before retrying.
Cause: A fatal error occurred during instance creation, a running operation, or hypervisor interaction. The fault details are stored in the instance record.Diagnosis:
Show error fault details
View full instance event log
Resolution:If the error is recoverable (e.g., a temporary network partition that has since resolved), attempt to rebuild the instance from its original image:
Rebuild instance from original image
If the error is caused by a host-level hardware failure, migrate the instance to a healthy host before attempting a rebuild. See Live Migration for instructions.
Rebuilding an instance replaces the root disk. Any data written to the root disk after initial provisioning will be lost. Ensure the instance owner has backed up root disk data before issuing a rebuild.
Cause: CPU compatibility mismatch, insufficient destination capacity, or a network timeout during the migration data transfer.Diagnosis:
Check migration status and error message
Show detailed migration information
Common errors and resolutions:See Live Migration for a full walkthrough of the migration procedure.
Cause: All compute hosts were eliminated by the scheduler filter chain — no eligible host satisfies the combined instance requirements.Diagnosis:
Check cluster-wide capacity
List all hosts with capacity details
Common causes:
If openstack hypervisor stats show reports available capacity but scheduling still fails, the Placement service inventory may be out of sync with actual host state. Trigger a resource reconciliation through the deployment console under Compute → Diagnostics → Reconcile Inventory.
Cause: The VNC or SPICE console proxy service is not running, the firewall is blocking the console port, or the console token has expired.Diagnosis:
Verify console proxy service status
Check all compute services for degraded state
Resolution:
  1. Verify ports 6080 (VNC), 6082 (SPICE), and 6083 (serial) are open in your firewall rules from the administrator’s workstation to the controller node.
  2. If the console proxy service is down, restart it through the deployment console under Compute → Services → Console Proxy.
  3. If the connection is refused immediately after generating a URL, the token may have expired. Generate a new console URL:
Generate a fresh console URL
Console tokens expire after a short period. If the browser reports an authentication error when accessing the console URL, always generate a new URL rather than refreshing the page.
See Console Access for firewall port requirements and proxy configuration details.
Cause: The project has reached its allocation limit for instances, vCPUs, or RAM. New instance creation or resize operations are blocked until the quota is increased or existing resources are released.Diagnosis:
Show current quota usage
List instances consuming quota in the project
Resolution:Option 1 — Increase the project quota:
Increase quota for instances, vCPUs, and RAM
Option 2 — Free capacity by removing unused instances:Coordinate with the project owner to identify and delete instances that are no longer in use. Do not delete instances without explicit confirmation from the project owner.
Before increasing quotas, verify the cluster has sufficient physical capacity with openstack hypervisor stats show. See Quota Management for quota adjustment procedures.

​
Next Steps

Compute Hosts

Monitor and manage hypervisor host health to prevent scheduling failures.

Live Migration

Move instances off degraded hosts before performing maintenance.

Admin Guide

Return to the Compute Administration Guide index.