Skip to content

Diagnose an application failure ​

Identify the operation that failed before choosing where to handle it. A rejected create call, an unmatched HTTP request and a failed message delivery each have a different owner. Diagnostic text helps locate the declaration. Prefer exit codes, statuses and your own error types for programmatic decisions.

When errors happen ​

Failure occurs during…Inspect firstRecovery
Importing a source fileDecorator target and optionsCorrect the declaration or compiler configuration
Creating the applicationModule scope, duplicate names, linker, eager factoriesCorrect the graph or configuration and create a fresh application
Executing a route, command or subscriptionInput, middleware and selected error policyHandle the failure at the relevant entry point
Closing a resourceDisposer and nested errorsInspect individual causes in the cleanup error

Dependency injection ​

Diagnostic or symptomWhat to check
Cannot resolve a dependency in a moduleStart at the module that declares the consumer. Check its providers and the exports of direct imports. Compare token identity
A token is ambiguousFind distinct declarations with the same token exported by two imports. Share the original declaration, use separate tokens or choose a local provider
A class is not injectableUse @Injectable() for class providers and put controllers in the module's controllers list
A circular import or dependencyFollow the reported chain. Move shared values into a module that both consumers can import without depending on each other
Failed to create … in module …Read error.cause for the factory or constructor exception. The failed declaration is cached within that injector
An override matches nothingReplace an existing provider token and import the exact token used in its declaration
The injector is disposedCheck that the owner outlives every consumer. Create a fresh application for the next test
AggregateError during releaseInspect error.errors for the failing declaration and its cause. Other resources are still given a chance to dispose

Module scopes · Provider lifetimes

HTTP ​

SymptomAction
Invalid route at definition or startupUse "" for the root or relative segments like "books/:id". Remove leading/trailing slashes and wildcards
Duplicate routeInspect complete paths and verbs. Parameter names are ignored when detecting a duplicate
app.mount fails during registrationCheck existing and proposed method/path pairs. Mount before Hono's first request or Fastify's readiness check
OpenAPI generation rejects an operation ID or security requirementGive each visible operation a unique ID and declare every referenced scheme in securitySchemes. API descriptions
ChoLinker needs the URL Pattern APICheck typeof URLPattern in the serving runtime or use a Hono linker
A validated argument arrives as raw textEnsure validate() covers the route. Inspect method.validated or enable cho:web
Middleware returned no responseReturn a Response or call next() exactly once
A @Catch logs an error but the client receives 500Return an explicit Response to handle the error. Logging alone leaves it unhandled
A 404 has the adapter's default bodyThe route was never selected. Compare the requested verb and full path with app.routes
An event stream ends with status 200 after a producer errorHeaders were already sent. Handle expected failures before returning the iterator and trace producer failures separately

Routing · Validation · Route errors

Messages and Kafka ​

SymptomAction
Empty or duplicate topicInspect the assembled topic and declaring module. Register each subscription once
start reports no linkerFor manual delivery call handle directly. For a broker attach a linker during creation
no handler for the topicCompare the full literal topic with app.routes, including the deployment prefix
The consumer acknowledges a record you expected to retryLook for a normally returning handler, a middleware that skips next(), or @Catch returning true
Retries stop intakeCheck retry exhaustion, dead-letter setup, producer errors and onFatal. The failed offset can remain uncommitted
An existing consumer group ignores from: "earliest"The adapter resumes committed offsets. from controls the fallback for a group without one

Delivery outcomes · Kafka policy

Command line ​

SymptomAction
No @Main or @Action methods foundRegister a decorated method's controller in a reachable module
Mixed @Main and @Action or duplicate actionsChoose one mode across the whole module graph. Give each action a unique name
An unknown action exits with 1Pass only the argument words to run. Compare with global --help
A flag consumes the action name or loses leading zerosDeclare value-taking global flags in parseOptions and identifier values as string
A command failure produces 2 unexpectedlyInspect the selected error handler for a thrown exception, as well as explicit code 2 returns
Help works but executing the action failsInspect the lazy provider or middleware construction for that action

Command selection · Flag parsing · Debug contexts

Released under the MIT License.