Diagnostics Reference

Every diagnostic code, what triggers it, and how to fix it.

Overview

SysMARA produces diagnostic codes when it detects issues in your spec files. Diagnostics are generated during sysmara build and sysmara doctor. Each code has a severity (error or warning) and a clear message explaining the problem.

Diagnostic codes follow a numbering scheme by category:

AX1xx: Duplicate Names

These errors indicate that two or more specs of the same type share the same name. Every spec name must be unique within its type.

Code Severity Description Fix
AX101 Error Duplicate entity name. Two entity specs have the same name. Rename one of the entities to a unique name, or remove the duplicate file.
AX102 Error Duplicate capability name. Two capability specs have the same name. Rename one of the capabilities to a unique name.
AX103 Error Duplicate policy name. Two policy specs have the same name. Rename one of the policies to a unique name.
AX104 Error Duplicate invariant name. Two invariant specs have the same name. Rename one of the invariants to a unique name.
AX105 Error Duplicate module name. Two module specs have the same name. Rename one of the modules to a unique name.
AX106 Error Duplicate flow name. Two flow specs have the same name. Rename one of the flows to a unique name.

AX2xx: Reference Resolution

These errors indicate that a spec references another spec by name, but that referenced spec does not exist.

Code Severity Description Fix
AX201 Error Capability references an entity that does not exist. Create the missing entity with sysmara add entity <name>, or fix the reference name.
AX202 Error Capability references a policy that does not exist. Create the missing policy or correct the policy name in the capability spec.
AX203 Error Capability references an invariant that does not exist. Create the missing invariant or correct the invariant name.
AX204 Error Policy references a capability that does not exist. Create the missing capability or correct the reference in the policy.
AX205 Error Invariant references an entity that does not exist. Create the missing entity or correct the entity reference in the invariant.
AX206 Error Flow references a capability that does not exist. Create the missing capability or correct the reference in the flow.
AX207 Error Flow step references an action that does not exist. Correct the action reference in the flow step.
AX208 Error Module references an entity that does not exist. Create the missing entity or remove it from the module's entity list.
AX209 Error Module references a capability that does not exist. Create the missing capability or remove it from the module's capability list.

AX3xx: Boundary Violations

These errors indicate that module boundary rules have been violated.

Code Severity Description Fix
AX301 Error Forbidden dependency. A module depends on another module that is in its forbidden_deps list. Remove the dependency or update the forbidden_deps list if the constraint is no longer valid.
AX302 Error Circular dependency. Two or more modules depend on each other in a cycle. Break the cycle by restructuring module boundaries or introducing an intermediate module.
AX303 Error Undefined dependency. A module declares a dependency on a module that does not exist. Create the missing module or correct the name in depends_on.
AX304 Error Cross-module entity reference. A capability in one module references an entity that belongs to a different module without a declared dependency. Add the other module to depends_on, or move the entity to the correct module.

AX4xx: Orphan Detection

These warnings indicate specs that are defined but never referenced by anything else in the system.

Code Severity Description Fix
AX401 Warning Orphaned entity. An entity exists but no capability references it. Create a capability that uses this entity, or remove the entity if it is no longer needed.
AX402 Warning Orphaned capability. A capability exists but is not included in any module. Add the capability to the appropriate module, or remove it.
AX403 Warning Orphaned policy. A policy exists but no capability references it. Attach the policy to a capability, or remove it.
AX404 Warning Orphaned invariant. An invariant exists but is not referenced by any capability. Reference the invariant from a capability, or remove it.

AX5xx: Safety Checks

These diagnostics identify potential safety or security concerns.

Code Severity Description Fix
AX501 Warning Missing manifest. A required manifest file is not present. Create the missing manifest file.
AX502 Warning Inconsistent zone. A spec is assigned to a zone that conflicts with its module's zone configuration. Align the zone assignment with the module's zone, or update the module's zone configuration.

AX6xx: Consistency Checks

These diagnostics detect logical inconsistencies in your spec definitions.

Code Severity Description Fix
AX601 Error Overlap in allowed and forbidden. A module lists the same dependency in both depends_on and forbidden_deps. Remove the module name from either depends_on or forbidden_deps. A dependency cannot be both allowed and forbidden.
AX602 Error Self-reference. A spec references itself, creating a trivial cycle. Remove the self-reference. A module should not list itself in depends_on or forbidden_deps.

MOD_* : Module Boundary Diagnostics

These are detailed diagnostic codes produced during module boundary validation (sysmara check boundaries).

Code Severity Description Fix
MOD_CONFLICTING_DEP Error A module lists the same module in both depends_on and forbidden_deps. Remove the conflicting entry from one of the two lists.
MOD_SELF_DEP Error A module lists itself in its depends_on. Remove the self-dependency. A module implicitly has access to its own contents.
MOD_SELF_FORBIDDEN Error A module lists itself in its forbidden_deps. Remove the self-reference from forbidden_deps.
MOD_UNDEFINED_DEP Error A module's depends_on references a module that does not exist. Create the missing module or correct the name.
MOD_UNDEFINED_FORBIDDEN_DEP Warning A module's forbidden_deps references a module that does not exist. Correct the module name or remove it from forbidden_deps.

CAP_BOUNDARY_* : Capability Boundary Diagnostics

These diagnostics are produced when a capability violates module boundary rules.

Code Severity Description Fix
CAP_BOUNDARY_UNDEFINED_MODULE Error A capability references a module that does not exist in its boundary context. Create the missing module or update the capability's module assignment.
CAP_BOUNDARY_VIOLATION Error A capability accesses an entity or capability from a module that is not in its module's depends_on list, or is in the forbidden_deps list. Add the required module to depends_on, move the capability to the correct module, or restructure your module boundaries.

INV_* : Invariant Diagnostics

These diagnostics are specific to invariant definitions.

Code Severity Description Fix
INV_DUPLICATE_NAME Error Two invariants share the same name. Rename one of the invariants to be unique.
INV_UNDEFINED_ENTITY Error An invariant references an entity that does not exist. Create the missing entity or correct the entity reference.
INV_INVALID_SEVERITY Error An invariant specifies an invalid severity level. Use a valid severity value as defined in the invariant schema.

Reading Diagnostic Output

When running sysmara build or sysmara doctor, diagnostics are displayed with their code, severity, and message:

AX201 [error] Capability "CreateOrder" references entity "Order" which does not exist.
AX401 [warning] Entity "LegacyAccount" is defined but never referenced by any capability.
MOD_CONFLICTING_DEP [error] Module "billing" lists "payments" in both depends_on and forbidden_deps.

Use --json to get structured output for programmatic processing:

npx sysmara build --json | jq '.diagnostics[] | select(.severity == "error")'