troubleshooting

Troubleshooting

Start by identifying the phase: Java compilation, generated metadata discovery, Guice injector creation, module LOAD/ENABLE, or Paper runtime callbacks. winter.debug=true in the boot module's compile-time configuration shows routine Winter messages at INFO; errors are logged regardless.

Symptom	Check
ProcessorModuleProvider cannot be found	@WinterBootPlugin is on the boot class; Winter is on annotationProcessor; a clean compile generated the boot package's autogenerated_winter_modules classes.
No components are discovered	Classes are public, concrete, and annotated with @Component or a one-level stereotype; nested classes are static; a compile-time interceptor did not discard them.
External component missing in a consumer	Producer generated META-INF/winter/components.index; its artifact is on the consumer's compile and annotation processor paths.
Exposed interface cannot be injected	Its implementation has @External, implements the @Expose interface, and is visible at runtime; inspect the index for binding:<interface>=<implementation>.
Generated API or ExposeAPIModule missing	API module uses winter.project.type=API with package/name, or the single module uses winter.expose.bypass-api=true; the consumer boot class package/name match the generated API.
Guice duplicate binding	Remove one of the overlapping @Primary, external, provider, or manual module bindings for the same key.
Accessing the injector fails in LOAD	Move that work to module/component ENABLE or use a LOAD-safe metadata/condition check.
Paper thread error	Add @SyncLoading to lifecycle work that reaches Bukkit/Paper indirectly, or schedule the specific operation through PluginScheduler.
A component has no disable callback	Check ENABLE conditions and interceptor/decorator decisions. Only enabled components receive DISABLE handler callbacks.
@RequiresExpr evaluates unexpectedly	Ensure the expression context exists before ENABLE and resolves to Boolean.TRUE. YAML contexts are added when the corresponding YamlConfig is created.
YAML binding or resource fails	Add @FileName to a field/parameter, include the matching .yml resource, and check the plugin data directory and YAML syntax.
Timed method never runs	Verify the containing component was enabled, expressions resolve to valid values, TimeUnit names such as SECONDS/MILLIS are used, and getZoneId() is correct for @ScheduledAt.

Useful local checks

./gradlew clean build
./gradlew :core:test :paper:compileJava
./gradlew :core:javadoc :paper:javadoc

On Windows use gradlew.bat. For a multi-module consumer, inspect the producer jar for META-INF/winter/components.index and the consumer build output for its generated module provider. When reporting a failure, include the phase, first exception and cause, relevant annotations, and the generated index entry if exports are involved.