Error Codes
All 21 VHYX_* error codes from @vhyxseal/core. VhyxSeal errors are always typed — never plain strings. Every error includes a severity level, structured context, and a concrete suggestion for how to fix it.
Errors at any severity level never crash the visual layer. In production, contract errors are logged silently and the component renders without a contract. In development, DevTools surfaces them prominently alongside a suggestion.
Schema Errors
| Code | Severity | Category | Description | How To Fix |
|---|---|---|---|---|
| VHYX_INVALID_SCHEMA_VERSION | error | Schema | The schema version string is not a valid semver | Ensure vhyxseal field is a valid semver string e.g. "1.0.0" |
| VHYX_CONTRACT_VALIDATION_FAILED | error | Schema | A contract failed structural validation — required fields are missing or wrong type | Check the error context for the specific field and value that failed |
| VHYX_UNKNOWN_INTENT | error | Schema | The intent string is not recognized and has no registered defaults | Use a built-in intent or call registerIntent() before using a custom intent |
| VHYX_INVALID_SAFETY_LEVEL | error | Schema | The safetyLevel value is not one of the five valid levels | Use one of: low | medium | high | critical | sensitive |
| VHYX_FIELD_TOO_LONG | error | Schema | A string field exceeds its maximum character limit | Shorten the field value — description: 500 chars, intent: 50 chars, consequence: 300 chars |
| VHYX_INJECTION_DETECTED | error | Schema | A string field matched an injection pattern and was rejected by sanitization | Remove prompt injection patterns from the field value — use plain descriptive text |
Manifest Errors
| Code | Severity | Category | Description | How To Fix |
|---|---|---|---|---|
| VHYX_MANIFEST_GENERATION_FAILED | fatal | Manifest | generateManifest() could not produce a valid manifest | Check the error context for the specific cause — often an invalid domain or empty contracts array |
| VHYX_MANIFEST_SIGNING_FAILED | error | Manifest | signManifest() failed — typically because no active signing key is registered | Register a signing key with rotateKey() before calling signManifest() |
| VHYX_MANIFEST_VERIFICATION_FAILED | error | Manifest | HMAC verification of a received manifest failed — signature does not match content | Ensure the manifest has not been tampered with in transit — re-fetch from source |
| VHYX_DOMAIN_MISMATCH | error | Manifest | The manifest domain field does not match the domain it is being served from | Ensure the domain field in ManifestConfig matches the actual serving domain |
Contract Errors
| Code | Severity | Category | Description | How To Fix |
|---|---|---|---|---|
| VHYX_CONTRACT_DRIFT_DETECTED | warning | Contract | A contract fingerprint does not match its recomputed value — contract content may have changed | Re-run defineContract() on the component to regenerate the fingerprint |
| VHYX_CONTRACT_STALE | warning | Contract | A contract has not been verified within the staleness threshold | Update lastVerified on the contract or set verifiedBy: "manual" after reviewing |
| VHYX_DUPLICATE_COMPONENT_ID | error | Contract | Two contracts were registered with the same component id on the same page | Ensure every component has a unique id within its SealProvider tree |
| VHYX_DUPLICATE_INTENT | warning | Contract | registerIntent() was called with an intent name that is already registered | Use a unique intent name — each intent can only be registered once |
Relationship Errors
| Code | Severity | Category | Description | How To Fix |
|---|---|---|---|---|
| VHYX_INVALID_RELATIONSHIP | error | Relationship | A relationship definition failed structural validation — required fields are missing | Check the relationship object against the schema in packages/core/src/schema/relationships.ts |
| VHYX_CIRCULAR_DEPENDENCY | fatal | Relationship | A dependency relationship forms a cycle — A → B → A | Break the circular dependency by removing one of the dependency definitions |
| VHYX_MISSING_COMPONENT_REF | warning | Relationship | A relationship references a component id that is not present in the active registry | Ensure the referenced component is mounted and registered before the relationship is resolved |
Security Errors
| Code | Severity | Category | Description | How To Fix |
|---|---|---|---|---|
| VHYX_RATE_LIMIT_EXCEEDED | error | Security | An agent exceeded the rate limit defined in AgentPolicy.rateLimits | Wait for the rate limit window to reset, or increase limits in AgentPolicy |
| VHYX_TOKEN_EXPIRED | error | Security | An action token was presented after its 60-second expiry window | Issue a new action token — tokens expire 60 seconds after issuance |
| VHYX_TOKEN_ALREADY_USED | error | Security | An action token was presented a second time after already being consumed | Issue a new single-use token for each action — tokens cannot be reused |
| VHYX_AGENT_NOT_ALLOWED | error | Security | The agent identity is blocked by AgentPolicy.blockedAgents or not in allowedAgents | Add the agent to AgentPolicy.allowedAgents or remove it from blockedAgents |