Error Code Reference

Complete reference for all error codes, status codes, and failure responses across every QuantaVirt subsystem — hypervisor core, VM lifecycle, CPU virtualization, memory management, storage, networking, PQC cryptography, QUAC 100 hardware, live migration, REST API, and CLI exit codes. Each entry includes the numeric value, symbolic name, human-readable description, common causes, and recommended recovery actions.

Error Code Overview #

QuantaVirt uses a unified error code system across all subsystems. Error codes are negative 32-bit signed integers organized by subsystem range. A value of 0 always indicates success.

Error Code Format #

Error codes appear in logs, CLI output, and API responses in a consistent format:

/* Log format */
[ERROR] quantavirt::vm: VM start failed: QV_ERR_NOVMX (-3): hardware virtualization not enabled in BIOS

/* CLI output */
$ quantavirt vm start my-vm
Error: QV_ERR_NOVMX (-3): Intel VMX / AMD SVM not available — enable in BIOS/UEFI

/* REST API JSON response */
{
  "error": {
    "code": -3,
    "name": "QV_ERR_NOVMX",
    "message": "Intel VMX / AMD SVM not available",
    "detail": "Enable hardware virtualization in BIOS/UEFI settings",
    "subsystem": "hypervisor"
  }
}

/* C API */
int ret = qv_vm_start(vm);
if (ret < 0) {
    fprintf(stderr, "Failed: %s (%d): %s\n",
            qv_strerror_name(ret), ret, qv_strerror(ret));
}

Hypervisor Core (QV_ERR_*) #

General hypervisor errors returned by core subsystem operations.

VM Lifecycle Errors #

CPU Virtualization Errors #

Memory Subsystem Errors #

Storage Subsystem Errors #

Network Subsystem Errors #

PQC Subsystem (PQC_ERR_*) #

QUAC 100 Hardware (QUAC100_ERR_*) #

Driver-level errors when communicating with the QUAC 100 PCIe card.

QUAC 100 Response Codes #

These are the 16-bit status codes returned in hardware response descriptors (see QUAC 100 Register Map → Response Codes). The driver translates them to QUAC100_ERR_* codes above.

Migration Errors #

REST API Error Responses #

The REST API returns standard HTTP status codes with a JSON error body containing the internal error code.

/* Example 409 Conflict response */
HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": -16,
    "name": "QV_ERR_STATE",
    "message": "Invalid state transition",
    "detail": "Cannot migrate VM 'web-server': current state is STOPPED (must be RUNNING)",
    "subsystem": "hypervisor",
    "request_id": "req-7a3b4c5d"
  }
}

CLI Exit Codes #

The quantavirt CLI maps internal error codes to standard Unix exit codes (0–125).

Linux errno Mapping #

When QuantaVirt errors originate from system calls, the original errno is preserved and mapped.

Diagnostic Commands #

Commands for investigating errors and collecting diagnostic information.

Look Up Error Code

$ quantavirt system error-lookup -3
QV_ERR_NOVMX (-3)
  Description: Intel VMX / AMD SVM hardware virtualization not available
  Subsystem:   hypervisor
  Severity:    fatal
  Common Causes:
    - Hardware virtualization disabled in BIOS/UEFI
    - CPU does not support VT-x (Intel) or AMD-V (AMD)
    - Another hypervisor (VirtualBox, VMware) has locked VMX
  Recovery:
    1. Enable VT-x/AMD-V in BIOS/UEFI firmware settings
    2. Verify: grep -c 'vmx\|svm' /proc/cpuinfo
    3. Unload conflicting hypervisors: rmmod kvm_intel kvm

Search Logs by Error Code

$ quantavirt log tail --level error --last 1h
[2026-01-15 14:32:01 UTC] [ERROR] storage: QV_STR_ERR_LOCK (-402): /var/lib/quantavirt/disks/web.qcow2 locked by VM 'web-prod' (pid 4821)
[2026-01-15 14:32:01 UTC] [ERROR] vm: QV_ERR_VM_START (-22): VM 'web-staging' start failed: disk locked

$ quantavirt log tail --grep "PQC_ERR" --last 24h
[2026-01-15 10:15:43 UTC] [WARN] pqc: PQC_ERR_QRNG (-113): QRNG pool depleted, waiting for refill (pool: 0/4096 bytes)
[2026-01-15 10:15:44 UTC] [INFO] pqc: QRNG pool recovered (pool: 2048/4096 bytes)

Generate Support Bundle

$ quantavirt system support-bundle --output /tmp/diag.tar.gz
Collecting system info...         done
Collecting hypervisor logs...     done (42 MB)
Collecting VM configurations...   done (14 VMs)
Collecting QUAC 100 diagnostics.. done
Collecting kernel messages...     done
Collecting network state...       done
Redacting sensitive data...       done

Support bundle: /tmp/diag.tar.gz (8.2 MB compressed)
Upload to: support@dyber.org

C API Error Handling Functions

/* Error introspection API */
const char* qv_strerror(int code);         // Human-readable description
const char* qv_strerror_name(int code);    // Symbolic name (e.g. "QV_ERR_NOMEM")
const char* qv_strerror_subsystem(int code); // Subsystem name
int         qv_error_is_transient(int code); // 1 if retryable (AGAIN, BUSY, TIMEOUT)
int         qv_error_to_errno(int code);     // Map to closest Linux errno

/* Example usage */
int ret = qv_vm_create(&vm, config);
if (ret < 0) {
    if (qv_error_is_transient(ret)) {
        sleep(1);
        ret = qv_vm_create(&vm, config);  // retry
    } else {
        fprintf(stderr, "Fatal: %s (%d): %s\n",
                qv_strerror_name(ret), ret, qv_strerror(ret));
        return EXIT_FAILURE;
    }
}