KSP diagnostics

Arc discovers your commands, read models and validation rules while the JVM compiler runs, through a KSP annotation processor. When it cannot make sense of a declaration it reports a diagnostic against that declaration rather than failing later at runtime or silently generating nothing.

Every diagnostic carries a stable code. Errors stop code generation, so the build fails and no artifact manifest is written. Warnings identify a convention that compiles but is probably not what you meant — most often a declaration Arc will ignore, which shows up later as a missing endpoint or a proxy that was never generated.

Codes are grouped by the artifact they concern: 01xx commands, 02xx queries and read models, 03xx proxy generation and validation, 04xx interoperability.

The C# implementation reports equivalent conventions through Roslyn analyzers with ARC codes; see code analysis. The two sets are not numbered alike, because each follows what its own compiler can see.

Diagnostics

Code	Severity	Description
`ARCKSP0001`	Error	Invalid KSP configuration
`ARCKSP0100`	Warning	Command-like type is missing @Command
`ARCKSP0101`	Error	Unsupported command declaration
`ARCKSP0102`	Error	Invalid command handle function
`ARCKSP0103`	Error	Invalid command provide function
`ARCKSP0104`	Error	Unsupported command method parameter
`ARCKSP0105`	Error	Unsupported command method return type
`ARCKSP0106`	Error	Ambiguous command key
`ARCKSP0107`	Warning	Provided value is not consumed by handle
`ARCKSP0108`	Error	Conflicting authorization metadata
`ARCKSP0109`	Error	Ambiguous command response values
`ARCKSP0110`	Error	Invalid command event metadata
`ARCKSP0200`	Error	Unsupported read model declaration
`ARCKSP0201`	Error	Invalid query function
`ARCKSP0202`	Error	Ambiguous query overload
`ARCKSP0203`	Error	Unsupported query parameter
`ARCKSP0204`	Error	Unsupported query return type
`ARCKSP0205`	Error	Query transport and return type disagree
`ARCKSP0206`	Error	Ambiguous or duplicate query route
`ARCKSP0207`	Error	Duplicate fully qualified query name
`ARCKSP0208`	Error	Invalid query infrastructure parameter
`ARCKSP0209`	Error	Unsupported Kotlin query parameter default
`ARCKSP0210`	Error	Invalid host query adapter shape
`ARCKSP0300`	Error	Unsupported generated proxy model shape
`ARCKSP0301`	Error	Invalid or unrepresentable Jakarta validation metadata
`ARCKSP0302`	Error	Ambiguous or unprovable Arc enum wire value
`ARCKSP0303`	Error	Missing or blank @DerivedType identifier
`ARCKSP0304`	Error	Unsupported @DerivedType declaration target
`ARCKSP0305`	Error	Concrete polymorphic base used as a property type
`ARCKSP0306`	Error	Unsupported @ExportedType declaration target
`ARCKSP0307`	Error	Unsupported identity details provider declaration
`ARCKSP0308`	Error	Unsupported fluent validation declaration
`ARCKSP0309`	Error	Invalid or unrepresentable fluent validation rule
`ARCKSP0310`	Error	Missing or conflicting fluent validation compiler metadata
`ARCKSP0311`	Error	Unsupported or ambiguous validation ignore member
`ARCKSP0400`	Warning	Java/Kotlin interoperability hazard
`ARCKSP9999`	Error	Unclassified Arc KSP diagnostic

When a diagnostic fires

A diagnostic names the declaration that caused it. Fix the declaration rather than suppressing the code: Arc only generates artifacts it can fully describe, so a suppressed error means the endpoint, proxy or validation rule you expected will not exist.

If you hit ARCKSP0001 the processor itself is misconfigured rather than your code being wrong — check that the io.cratis.arc Gradle plugin is applied and that KSP is on the compile path, as described in getting started.