Every error raised by NeuronScope includes an E-prefixed error code, exception class name, human-readable cause description, and a mechanical remedy hint.
Error Code Reference Table
| Code | Name | Category | Cause | Remedy |
|---|---|---|---|---|
| E001 | FingerprintMismatch | Identity | Two objects that should be equal produced different canonical fingerprints. | Compare inputs with ns.fingerprint_diff to find the parameter or schema drift. |
| E002 | UnknownAdapter | Runtime | No adapter is registered for the specified framework or model object. | Install the matching extra, e.g. pip install 'neuronscope[torch]' or register adapter. |
| E003 | ProbeIncompatibleWithModel | Observability | The probe selector requested layer paths that the model architecture cannot resolve. | Check selector globs against ns.Scope(model).selected_modules(). |
| E004 | ArtifactSchemaTooNew | Storage | The .nsz artifact was written by a newer platform major version. | Upgrade NeuronScope using pip install --upgrade neuronscope. |
| E005 | ArtifactSchemaTooOld | Storage | The .nsz artifact predates the minimum supported schema contract. | Migrate artifact using ns migrate <artifact> --to 0.9.2. |
| E006 | NonDeterministicOp | Reproducibility | deterministic=True was set but an un-seeded non-deterministic op ran. | Call ns.seed_all(seed) or pass deterministic=False. |
| E007 | SealAfterClose | Lifecycle | Attempted to write telemetry to a scope after it had been sealed. | Ensure all execution calls occur inside the with ns.Scope() context block. |
| E008 | PromptCanonicalizationError | Prompt Engine | Prompt object contains un-hashable or un-canonicalized variable bindings. | Convert prompt variables to primitive types (str, int, float, list, dict). |
| E009 | StorageBackendUnavailable | Storage | Cloud storage protocol (s3, gcs, azure) lacks required driver dependency. | Install cloud extra, e.g. pip install 'neuronscope[s3]'. |
| E010 | PluginContractMismatch | Plugin System | Loaded plugin targets an incompatible platform API major version. | Update the plugin or re-run ns plugins doctor. |
| E4002 | HallucinationThresholdExceeded | Governance | Evaluation score exceeded maximum allowed hallucination threshold in CI. | Review retrieved RAG documents or prompt variables, or raise tolerance threshold. |
| E4005 | SecurityPolicyViolation | Security | Prompt variable contained prompt injection threat or un-redacted PII. | Sanitize prompt inputs or adjust governance security rules. |
Error Attributes & Exception Handling
In Python code, inspect err.code, err.name, and err.hint for programmatic exception handling and automated logging.