Fix Koin Issues with Kotzilla MCP Server

When the Koin Compiler Plugin reports an error in your build — or when a Koin runtime exception is thrown — you can ask your AI coding assistant to fix it. The Kotzilla MCP Server recognizes Koin compile errors and runtime exceptions, returns a step-by-step fix workflow, and the assistant applies the change in your code under your review.

This page is for developers who hit a Koin issue and clicked the link in the error message. No prior Kotzilla setup is required other than installing the MCP Server in your assistant.

Quick start

1. Install the Kotzilla MCP Server in your assistant

The Kotzilla MCP Server endpoint is:

https://mcp.kotzilla.io/mcp

It speaks the streamable HTTP MCP transport. You will need a free Kotzilla account — the MCP Server prompts for authentication on first use.

Claude Code — one command from your terminal:

claude mcp add kotzilla --transport http https://mcp.kotzilla.io/mcp

Cursor, Windsurf, Android Studio, and other MCP-compatible tools — see the full per-client instructions in the MCP Server setup guide. Clients that do not yet support streamable HTTP can use the mcp-remote bridge documented there. For background on what the server does end-to-end, see the MCP Server overview.

2. Copy the full Koin error or stacktrace

From your build output or runtime crash log, copy the entire error. The more context the classifier gets, the more precise the workflow.

• Compile errors: copy the [Koin]... block including every indented line under the first line (qualifier, required-by, in-module, hints).
• Runtime exceptions: copy the entire stacktrace — including the full Caused by: chain and the frames mentioning org.koin.core.*. The classifier identifies the exception class, and the workflow uses the stacktrace to point the assistant at the right caller and inner cause.

Do not paste only the first line. Single-line pastes lose the entities the classifier extracts.

3. Paste it to your assistant

With a prompt like "Fix this Koin error". The assistant calls the MCP Server, which classifies the error and returns a fix workflow. The assistant then walks you through it: inspecting your project, proposing a concrete edit, and verifying with a rebuild before completing.

Example walkthrough

Suppose your build fails with:

[Koin][KOIN-D001] Missing dependency: com.example.Repository qualified with @Named("prod")
  required by: Service (parameter 'repo')
  in module: appModule
  Hint: Found similar binding: Repository with qualifier @Named("test")
  → Fix with AI: set up Kotzilla MCP at https://kotzilla.io/mcp

Paste this error to your assistant. The MCP Server identifies it as KOIN-D001 (missing binding) and returns a workflow. The assistant will:

1. Acknowledge the diagnosis: a Repository qualified @Named("prod") is needed by Service.repo in appModule.
2. Gather context: search your project for existing Repository providers and definitions.
3. Propose a fix. Based on what it finds, you typically get one of:
   • Add a new single<Repository>(named("prod")) { ... } definition in appModule.
   • Switch the consumer to @Named("test") if that is the existing binding.
   • Include the module that already defines Repository.
   • Mark the parameter @Provided if the dependency comes from outside Koin.
4. Apply the edit after your confirmation.
5. Verify by rebuilding the affected module.

The same flow works for all supported error categories below.

Supported error categories

Each Koin compile error includes an error code in brackets (for example [KOIN-D001]). The MCP Server recognizes the following:

Code	What it means
KOIN-D001	Missing dependency on a constructor or function parameter
KOIN-D002	A call to koinInject<T>() / get<T>() cannot be resolved
KOIN-D003	A call site in a dependency module cannot be resolved at the app
KOIN-W001	A module is not loaded at startKoin and its definitions are unreachable
KOIN-A001	@KoinViewModel is used but koin-core-viewmodel is missing
KOIN-A002	@KoinWorker is used but koin-android-workmanager is missing
KOIN-A003	@Module is used but koin-core is missing
KOIN-S001	create(::T) is not the only statement in its lambda
KOIN-P001	@Property has no matching @PropertyValue default
KOIN-M001	@Monitor is used but the Kotzilla SDK is not on the classpath

If your error matches one of these codes, the assistant has a deterministic workflow for it. If it does not, the assistant can still help, but the diagnosis will rely on general reasoning rather than a curated playbook.

Runtime errors and stacktraces

The MCP Server also classifies Koin runtime exceptions. Paste the full stacktrace — not just the exception line. The classifier locks onto the exception class name, and the workflow uses the rest of the stack to find the actual caller and the inner cause.

Supported exceptions:

• NoBeanDefFoundException — no definition found for a requested type.
• InstanceCreationException — a definition failed during construction. The workflow recurses into the Caused by: chain.
• NoScopeDefFoundException / ScopeNotCreatedException — scope not declared or not opened.
• ClosedScopeException — the scope was closed before the lookup.
• DefinitionOverrideException — two definitions claim the same type.
• Circular dependency errors — detected via StackOverflowError with repeated org.koin.core.scope.Scope.resolveInstance frames.

What to include in the paste:

• The exception type and message (e.g. org.koin.core.error.NoBeanDefFoundException: No definition found for class:'com.example.X').
• All stack frames, especially those mentioning org.koin.core.*.
• The full Caused by: chain if there is one — for InstanceCreationException in particular, the inner cause is where the real problem lives.

The longer the paste, the more the classifier and the workflow can extract: type name, qualifier, scope id, the caller frame, and the inner cause class.

Privacy and data

When you paste an error to your assistant and it forwards the text to the Kotzilla MCP Server:

• What is sent: the pasted error or stacktrace text, plus the structured queries the workflow makes (for example "providers of type X").
• What is not sent: your source files, secrets, or any code your assistant does not explicitly forward.
• Storage: see the Kotzilla data policy for retention and processing details.

All communication between the MCP Server and the Kotzilla Platform is encrypted over HTTPS.

Do I need a Kotzilla account?

Yes, but the account is free. The MCP Server requires authentication so usage can be associated with an account; sign up at console.kotzilla.io. You do not need to install the Kotzilla SDK or capture sessions to use the compile-error workflow.

If you later want runtime performance and stability analysis on top of this, you can install the SDK from the same account. See the MCP Server overview for the broader capabilities.

Turn off the AI hint in error messages

The → Fix with AI line in Koin compile errors is controlled by the aiAssist option in the Koin Compiler Plugin:

// build.gradle.kts
koinCompiler {
    aiAssist = false   // remove the AI hint from error messages
}

This only removes the hint line. It does not change which errors are reported or how they are formatted otherwise.

FAQ

The error message I see does not have a [KOIN-*] code. Codes were added in Koin Compiler Plugin 1.0+. Upgrade the plugin to get classification-friendly error messages, or paste your error to the assistant as-is — the MCP Server can still classify common patterns.

The proposed fix did not work. The workflow re-runs the classifier on the new error and tries once more. If it still fails, it escalates to you with the diagnostic output collected so far. From there your assistant can reason further with full context.

Can I use this without an AI assistant? The MCP Server is designed for assistant-driven workflows. For interactive debugging without AI, use the Koin IDE Plugin for in-editor validation.

Need help?

Hit an error the workflow did not solve? Reach out with the error text and we will improve the classifier.