Diagnostics
Every generator and analyzer diagnostic Elarion can emit, what it means, and how to fix it.
Elarion's source generators and its module-boundary analyzer report problems as compiler diagnostics at build time, so unsupported patterns fail (or warn) deterministically instead of breaking at runtime. Each diagnostic below lists its id, severity, what it means, and how to fix it, grouped by prefix and sorted by id.
Looking for help by symptom (a build error message, a missing endpoint, a handler that never runs) rather than by id? Start with Troubleshooting, then come back here for the specific diagnostic.
ELRPC — JSON-RPC method generation
JSON-RPC method emission for [RpcMethod] handlers. See
JSON-RPC.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELRPC001 | Warning | An [RpcMethod] handler's namespace is not under any [AppModule]; it is registered unconditionally (not gated by a module feature flag). MCP reuses this id since it is built on [RpcMethod]. | Move the handler under a module's namespace so its RPC/MCP registration is module-scoped and feature-gated. |
| ELRPC002 | Warning | An [RpcMethod] handler does not implement IHandler<TRequest, TResponse> with a Result<T> response, so no RPC method can be generated. | Make the handler implement IHandler<TRequest, Result<TResponse>> (or the IHandler<T> sugar) so the request/response shape is resolvable. |
ELHTTP — HTTP endpoint generation
Minimal-API endpoint emission for [HttpEndpoint] handlers. See
HTTP endpoints.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELHTTP001 | Warning | An [HttpEndpoint] handler does not implement IHandler<TRequest, TResponse> with a Result<T> response, so no endpoint can be generated. | Make the handler implement IHandler<TRequest, Result<TResponse>> (or the IHandler<T> sugar) so the request/response shape is resolvable. |
| ELHTTP002 | Warning | Two handlers map the same HTTP verb + route template (for example, the same GET /x). | Change one handler's verb or route template so each verb+route pair is unique. |
| ELHTTP003 | Warning | An [HttpEndpoint] handler's namespace is not under any [AppModule]; it is mapped unconditionally (not gated by any module feature flag) so it is never silently dropped. | Move the handler under a module's namespace so its endpoint is module-scoped and feature-gated. |
| ELHTTP004 | Warning | An [HttpEndpoint] has no explicit verb and its request implements neither ICommand (POST) nor IQuery (GET), so the verb cannot be inferred. | Specify an explicit verb on [HttpEndpoint], or make the request implement ICommand (POST) or IQuery (GET). |
ELMCP — MCP customization
MCP tool customization for [McpMethod]. See MCP.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELMCP003 | Warning | A handler carries [McpMethod] (tool-name customization) but its [RpcMethod] Transports flag does not include RpcTransports.Mcp, so the customization has no effect. | Remove [McpMethod], or include RpcTransports.Mcp in the handler's [RpcMethod] Transports. |
ELEVT — Event consumers
Event-consumer discovery for [ConsumeEvent]. See Consuming events.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELEVT001 | Error | A method-form [ConsumeEvent] consumer method is declared on a class that is not annotated with [Service]. | Declare the consumer method on a [Service] class, or use the handler-form consumer instead. |
| ELEVT002 | Error | A method-form [ConsumeEvent] consumer has an unsupported signature. It must be an accessible, non-generic, non-static instance method accepting exactly one IDomainEvent/IIntegrationEvent parameter (optionally IEventContext and/or CancellationToken) and returning void/Task/ValueTask (subscriber) or Result<T> (domain responder). | Take one event parameter (optionally IEventContext and/or CancellationToken), return void/Task/ValueTask for a subscriber or Result<T> for a domain responder, and make it an accessible, non-generic, non-static instance method. |
| ELEVT003 | Warning | A [ConsumeEvent] consumer's namespace is not under any [AppModule], so it will not be registered. | Move the consumer under a module's namespace so it is wired by that module. |
| ELEVT004 | Error | More than one responder is declared for the same request type (RequestAsync requires exactly one responder per request type). | Keep exactly one responder for the request type; remove or convert the duplicates. |
| ELEVT005 | Error | A class-level [ConsumeEvent] is on a type that does not implement exactly one IHandler<TEvent, Result<TResponse>> (or IHandler<TEvent>) whose request is an IDomainEvent/IIntegrationEvent; or an integration-event handler returns a non-Unit Result<T> (integration events are fan-out only); or the marker is on a non-handler. | Implement exactly one IHandler<TEvent, Result<TResponse>> (or IHandler<TEvent>) whose request is an IDomainEvent/IIntegrationEvent; for integration events return Result<Unit> (or use IHandler<TEvent>) since they are fan-out only. |
ELMOD — Module boundaries
App-module discovery and the ModuleBoundaryAnalyzer. See
Modules and Cross-module communication.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELMOD001 | Warning | Two [AppModule] types share the same namespace; generated transport handlers in that namespace are associated with the alphabetically first matching module (ambiguous ownership). | Give each module a distinct namespace so handler-to-module association is unambiguous. |
| ELMOD002 | Warning | A type in one [AppModule] depends (via constructor parameter, field, or property) on another module's internal type — a [Service], a handler, or a [DbEntity] entity — rather than a published [ModuleContract]. Types under no module are never flagged. | Depend on the other module's published [ModuleContract] interface instead of its internal service/handler/entity types. |
ELAPI — Module API facades
Typed in-process module API generation for [GenerateModuleApi] / [ModuleApi]. See
Cross-module communication.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELAPI001 | Error | An interface annotated with [GenerateModuleApi] is not declared partial, so the generated members cannot be emitted into it. | Declare the [GenerateModuleApi] interface as partial. |
| ELAPI002 | Error | A [GenerateModuleApi] interface is nested inside another type instead of being declared at namespace scope. | Move the [GenerateModuleApi] interface to namespace (top-level) scope. |
| ELAPI003 | Warning | A [GenerateModuleApi] interface's namespace is not under any [AppModule], so no handlers can be associated and the facade is left empty. | Move the facade interface under a module's namespace so its handlers can be discovered. |
| ELAPI004 | Error | A [GenerateModuleApi] facade maps more than one handler to the same method name (handlers share a type name); the duplicate handler is skipped. | Rename one of the conflicting handler types, or exclude one via [ModuleApi(Exclude = true)], so each facade method name is unique. |
ELKEY — Keyset pagination
Keyset-definition generation for [Keyset<TEntity>]. See Pagination.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELKEY001 | Error | A [Keyset] declares a column name that does not match any property on the target entity; no keyset is generated. | Correct the keyset column name to match an existing entity property. |
| ELKEY002 | Error | A [Keyset] column maps to a property whose type is not supported for keyset pagination; no keyset is generated. | Use a supported (comparable) column type for keyset ordering, or remove that column from the keyset. |
| ELKEY003 | Error | A [Keyset] column maps to a nullable property; keyset columns must be non-nullable for deterministic ordering. No keyset is generated. | Make the keyset column non-nullable, or choose a different non-nullable column for the ordering. |
| ELKEY004 | Warning | The target entity has an Id property that is not part of its [Keyset], so paging order may not be deterministic (no unique tiebreaker). | Append a unique column (such as the key/Id) to the keyset so ordering is deterministic. |
| ELKEY005 | Error | A [Keyset<TEntity>]-annotated class is nested or non-partial; the generator emits the IKeysetDefinition implementation into it and requires a non-nested partial class. | Declare the keyset class as a top-level (non-nested) partial class. |
ELSG — Services, scheduled jobs
Service registration and scheduled-job discovery. See Services and Scheduling.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELSG001 | Error | A [Service] class that is an IHostedService/BackgroundService is registered with a non-singleton ServiceScope. Hosted services must be singletons. | Set the service's scope to ServiceScope.Singleton on its [Service] attribute. |
| ELSG002 | Error | A [Service] declares an explicit contract type that the implementation class is not assignable to. | Make the implementation implement/inherit the declared contract, or correct the contract type on the [Service] attribute so it matches the implementation. |
| ELSG003 | Error | A [Service] is declared on a generic (open) class; the generator cannot register an open-generic service. | Make the service a non-generic (closed) class, or register the open generic manually outside the generator. |
| ELSG004 | Error | A [ScheduledJob] method has an unsupported signature. It must be accessible, non-generic, return Task/ValueTask, and accept only IScheduledJobContext and/or CancellationToken parameters. | Make the method accessible and non-generic, return Task/ValueTask, and take only IScheduledJobContext and/or CancellationToken. |
| ELSG005 | Error | A scheduled-job type is generic or is nested inside a generic type. | Make the job type non-generic and not nested in a generic type. |
| ELSG006 | Error | A runtime-schedulable job type does not implement exactly one IScheduledJob<TPayload> interface (zero or more than one). | Implement exactly one IScheduledJob<TPayload> on the job type. |
| ELSG007 | Error | Two or more scheduled jobs declare the same job name. Names must be unique. | Give each scheduled job a unique name. |
| ELSG008 | Error | A scheduled job's schedule is invalid: it must declare exactly one of FixedRate, FixedDelay, Cron, or InitialDelay-only one-time scheduling, and InitialDelay/RunOnStart cannot be combined with Cron. | Specify exactly one schedule mode, and do not combine InitialDelay/RunOnStart with Cron. |
| ELSG009 | Error | A scheduled job's MaxConcurrentRuns is negative (must be 0 or greater). | Set MaxConcurrentRuns to 0 (unbounded) or a positive integer. |
| ELSG010 | Warning | A [ScheduledJob] type's namespace is not under any [AppModule]; under a module-bootstrapper host it will not be registered. | Move the job under a module's namespace so it is wired by that module's gated registration. |
ELPIPE — Decorator pipelines
Decorator attachment in handler registration. See Decorator pipelines.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| ELPIPE001 | Error | A decorator declares an AppliesTo attachment-predicate method that is not public, so the generated registration cannot call it to decide attachment. | Declare the predicate as public static bool AppliesTo(System.Type request). |
WFRE — Resilience policies
Resilience-policy registration for [ResiliencePolicy]. See Resilience.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| WFRE001 | Error | A [ResiliencePolicy] is invalid (the message includes the specific reason, for example bad option values). | Correct the resilience policy configuration per the reason in the diagnostic message. |
| WFRE002 | Error | Two or more resilience policies declare the same policy name. | Give each resilience policy a unique name. |
WIMCACHE — Handler caching
Handler caching configuration for [Cacheable] / [CacheInvalidate]. See Caching.
| Id | Severity | Meaning | Fix |
|---|---|---|---|
| WIMCACHE001 | Error | A handler is annotated with both [Cacheable] and [CacheInvalidate]; these are mutually exclusive. | Apply only one of [Cacheable] or [CacheInvalidate] to the handler. |
| WIMCACHE002 | Error | A handler's cache configuration defines no non-empty cache tag (at least one is required). | Define at least one non-empty cache tag on the handler's caching attribute. |
| WIMCACHE003 | Error | A handler declares a cache tag that fails validation (invalid format/value). | Replace the invalid cache tag with a valid tag value. |
| WIMCACHE004 | Error | A cacheable handler's cache duration is not positive (must define a positive duration). | Set a positive cache duration on the handler's [Cacheable] configuration. |