Troubleshooting

Most Pyvorin failures announce themselves precisely. The product fails conservatively — it keeps your program correct, records what happened, and names the reason — which means nearly every error message you will meet has one cause and one fix. This page lists the failures in the order you are likely to meet them, each verified against the installed 1.0.9 build.

The symptom table

The rest of the page works through the rows that deserve more than a line, in the order a diagnosis usually unfolds: integrity first, then licensing, then compilation, then performance.

Integrity failures at import

At import, pyvorin-native SHA-256-hashes every compiled module against a hash table baked into the build and raises a RuntimeError naming tampering on the first mismatch. In practice the trigger is mundane: a pip install that overwrote part of the tree, a partially copied container image, an antivirus or backup agent that touched a shared object. The fix is always the same — reinstall the wheel into a clean environment and let the hashes match again.

PYVORIN_DEV_MODE=1 skips the check. It exists so developers can iterate on the package itself. It must never appear in a production environment, and its presence there is itself a finding — see the security best practices page.

Licence-gate failures

pyvorin check exits 1 with License gate failed: followed by both reasons — the local failure and the network failure. Read both. A corrupted license.json fails locally; an unreachable licence endpoint fails online; a rebuilt host fails on identity, because the stored device fingerprint is SHA-256 of hostname:username:/etc/machine-id and any of those changing invalidates the file. Recovery is re-activation with the same key. If the server must be reached through a proxy, PYVORIN_LICENSE_URL overrides the endpoint — set it deliberately and audit it, because anything that can set that variable can redirect your licence traffic.

Two softer variants. A licence that validates offline passes the gate even when online revalidation fails, so a network partition alone will not stop your pipelines. And after genuine expiry there is an offline grace window — 24 hours for trial tiers, 72 hours for basic and professional, 90 days for enterprise — before compiled features stop, so a missed expiry warning is recoverable rather than instant.

Compile declines and exit codes

The compile report's per-function status is the truth to read. FAILED with an oracle-mismatch message means the compiler produced native code, ran both it and CPython on the same inputs, and the results disagreed; the tooling discards the claim rather than ship the doubt, and no configuration in 1.0.9 overrides that. The route past it is a code change or a fix from us.

Exit 2 under --fail-on-fallback covers two situations the code alone does not separate: a genuine fallback (read fallback_used: true and fallback_reason in the JSON report) and a compile whose oracle never ran because the function requires arguments (cpython_oracle_status: "not_run"). The remedy for the second is usually structural — expose a zero-argument entrypoint the oracle can exercise — and it is worth doing, because an unvalidated compile is a compile you cannot yet claim. The complete taxonomy lives on the error handling and diagnostics page.

The support-vs-compile status divergence

On a file containing a generator function, we watched support report every function as COMPILED_PARTIAL with one unsupported feature — while compile on the same file reported COMPILED_FULL for the plain functions and annotated them Runtime validation not performed: function requires arguments. Same file, same build, two status vocabularies. The divergence is cosmetic but expensive if you script against the wrong one: trust the compile report for compilation truth, use support for the per-feature unsupported list, and read the full worked example on the debugging compiled code page.

No speedup

The most common "fault" is not a fault. In the canonical 71-workload benchmark run, seventeen workloads ran slower under Pyvorin than under CPython, concentrated in string manipulation (category geomean 0.85x), parsing (0.86x), compression (0.19x) and web request handling (0.97x) — code that spends its time inside C library routines or allocating short-lived objects, where there is little interpreted bytecode left to remove and the compiled path's fixed overheads show through. The worst cases, 0.05x, are micro-workloads whose entire runtime is smaller than the compilation cost — the same suite contains a simulation workload at 180.5x, so scale, not category alone, is the discriminator. Before concluding anything from a slow number, check the measurement itself: a cold compile inside a short timed window poisons the first runs, so respect --warmup and compare steady-state timings from the timing block rather than wall clock. Diagnose with python -m pyvorin bench your_file.py --json and read the per-category expectations on the supported workloads page before assuming anything is broken.

Cache problems

The compile cache is keyed by the SHA-256 of source, function, options and runtime state, is LRU-capped at 500 entries, and validates a checksum on every entry — so a corrupted artefact is reported on load rather than executed. That validation makes most cache trouble self-healing: clear and rebuild.

# Inspect
python -m pyvorin cache status
# Cache directory: /root/.pyvorin_cache
# Total files: 158
# Total size: 1.20 MB

# Rebuild from scratch
python -m pyvorin cache clear

Know the three locations so you clear the right one: the compiled-artefact cache inside the install tree at <site-packages>/.pyvorin_cache/disk_compile, the runtime cache at ~/.pyvorin_cache/ (created at import, before any activation), and XDG state under ~/.cache/pyvorin. None of them contains licence material — that lives in ~/.pyvorin/ and you should not delete it as a cache-cleaning step. If clearing the cache does not clear the symptom, the corruption was never in the cache: re-run doctor and check the integrity row, because a hash failure and a cache failure can present with the same face — a program that refuses to start — and the fix for each is different.

When to stop troubleshooting

The judgement this page cannot make for you is when a symptom is expected behaviour. Our rule after running these commands for months: if the fallback logger shows a function on the compatibility path with correct: true, that is not an incident to fix — it is the product declining work it cannot accelerate while preserving your results, and chasing it burns time that belongs on the functions the compiler can take. Troubleshoot FAILED, drift_detected and licence failures without mercy; leave honest fallbacks alone and revisit them at migration time. The distinction between "broken" and "declined" is the whole game.

Where to go next

• Pyvorin CLI reference — the exact flags and exit codes behind every fix above.
• Error handling and diagnostics — the failure taxonomy and where every diagnostic record lives.
• Debugging compiled code — the support/compile divergence and caller-taint mechanics in full.
• Unsupported code and the fallback path — when a fallback is the correct outcome.

Last reviewed 20 July 2026 against pyvorin-native 1.0.9 installed at /root/pvfinal. Every error message, exit code and command output quoted here was reproduced in real runs on 13 September 2026; no symptom on this page is described from documentation alone.