Quick diagnostics

Run this in your environment:

import vortex_pqc

print(f"version:  {vortex_pqc.__version__}")
print(f"backend:  {vortex_pqc.native_backend()}")
print(f"pk size:  {vortex_pqc.PUBLIC_KEY_BYTES}")
print(f"sk size:  {vortex_pqc.PRIVATE_KEY_BYTES}")
print(f"ct size:  {vortex_pqc.CIPHERTEXT_BYTES}")

kp = vortex_pqc.generate_keypair()
ct = vortex_pqc.encapsulate(kp.public_key)
ss = vortex_pqc.decapsulate(ct.data, kp.private_key)
print(f"round-trip: {'OK' if ss == ct.shared_secret else 'FAILED'}")

Expected:

version:  0.1.0
backend:  vortex-pqc-native-aarch64   (or vortex-pqc-pure-python)
pk size:  800
sk size:  1248
ct size:  768
round-trip: OK

Error reference

Error	Cause	Fix
Invalid public key length: expected 800, got N	Wrong byte count passed to encapsulate()	Ensure exactly 800 bytes. Check for truncation, encoding, or wrong key type.
Invalid ciphertext length: expected 768, got N	Wrong byte count passed to decapsulate()	Ensure exactly 768 bytes. Verify transport framing doesn't corrupt payload.
Invalid private key length: expected 1248, got N	Wrong byte count passed to decapsulate()	Ensure exactly 1248 bytes. Re-read PEM with correct PEMKind.PRIVATE_KEY.
invalid data length for PUBLIC KEY	PEM encode with wrong-sized bytes	Pass exactly 800 bytes to encode_pem(PEMKind.PUBLIC_KEY, ...)
missing or invalid PEM block	Malformed PEM file or wrong kind	Check BEGIN/END labels match VORTEX256 format. See PEM spec.
invalid Base64 payload	Corrupted PEM body	Re-encode from raw bytes. Check for line wrapping issues.
SecurityError: Decapsulation failed	Native backend integrity check (rare)	Verify ciphertext and private key are from the same key pair.
Shared secrets don't match	Key mismatch or tampered ciphertext	See debugging guide below
ModuleNotFoundError: vortex_pqc	Package not installed	pip install vortex-pqc
Native backend not available	C extension didn't compile	Install C compiler and reinstall: pip install -e . --force-reinstall

Shared secrets don't match

Checklist

□  pk and sk came from the same generate_keypair() call
□  ct.data is exactly 768 bytes (not hex-encoded, not base64 on wire)
□  No byte corruption during network transfer
□  Not comparing against a different encapsulation's shared_secret
□  Using decapsulate(ct.data, sk) not decapsulate(ct, sk) — ct is a Ciphertext tuple

Backend issues

Force pure Python for debugging

mv src/vortex_pqc/_native*.so /tmp/ 2>/dev/null
python -m pytest src/tests/ -v

If tests pass in pure Python but fail in native → C extension bug. Rebuild:

pip install -e . --force-reinstall --no-deps

Verify C library independently

make -C c clean test

Installation issues

pip install fails on C extension (non-fatal)

The package installs without the native extension. You'll get vortex-pqc-pure-python backend. To fix:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3-dev

pip install -e . --force-reinstall

PEP 668 externally-managed-environment

python3 -m venv .venv
source .venv/bin/activate
pip install vortex-pqc

Getting help

Channel	When
FAQ	Common questions
GitHub Issues	Bugs, feature requests
hello@bajpailabs.com	Security vulnerabilities (private)

When filing a bug, include:

- vortex_pqc.__version__
- vortex_pqc.native_backend()
- Python version and OS
- Minimal reproduction script
- Full error message and traceback