> For the complete documentation index, see [llms.txt](https://docs.lithnet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lithnet.io/ecma2-framework/additional-resources/troubleshooting.md). # Troubleshooting This page covers the problems you're most likely to hit when running a management agent built with version 3 of the framework. The [architecture overview](/ecma2-framework/concepts/architecture-overview.md) describes the parts referred to below: the shim that MIM loads, the worker process it launches, and the registry value that links them. ## The management agent doesn't appear in MIM If your agent isn't listed when you create a new management agent, the **Packaged MA manifest** is most likely missing or in the wrong place. Confirm the manifest XML was installed into the Synchronization Service's `UIShell\XMLs\PackagedMAs` folder, and restart the MIM Synchronization Service Manager so it re-reads that folder. ## A run step fails immediately, or the connection can't be opened When MIM starts an operation, the shim has to launch the worker. If it can't, the operation fails right away. The usual cause is a missing or incorrect **worker path**. The shim finds the worker by reading this registry value (64-bit view): ``` HKEY_LOCAL_MACHINE\Software\Lithnet\Ecma2\.Ecma2 WorkerPath = ``` Check that: * the value exists under the sub-key named after your shim assembly (`.Ecma2`); * it points at the `Ecma2Host.exe` that your installer actually deployed; and * the file is present at that path. If the value is missing, the shim raises an error that names both the registry key it looked for and the `LITHNET_ECMA2_WORKER_EXE` environment-variable override, so the MIM run-step error usually tells you exactly what wasn't configured. Your installer is responsible for writing this value; see [Packaging and deployment](/ecma2-framework/deployment/packaging-and-deployment.md). > **For development and testing**, you can set the `LITHNET_ECMA2_WORKER_EXE` environment variable to the full path of a worker you built locally. It takes precedence over the registry value, so you can point MIM at a fresh build without reinstalling. ## "Refresh interfaces" fails, or the agent won't load at all If MIM can't load the shim when you refresh interfaces or open the agent, check the **Application event log** on the MIM server for the underlying error. The shim is a small .NET Framework 4.8 assembly, so the server needs .NET Framework 4.8 installed (it is present on any supported MIM server). Unlike older versions of the framework, the shim has no third-party dependencies, so the DLL-conflict and embedded-assembly errors that affected in-process agents no longer apply. ## The worker starts but then fails Because your provider runs in the worker process, errors in your own code surface there. The worker logs to the Windows event log and can be configured to log to a file. Start there when an import or export runs but produces unexpected results or per-object errors. The worker is published self-contained, so it carries its own copy of the .NET runtime and the server does not need .NET installed. If you instead deployed a framework-dependent build (the output of `dotnet build` rather than `dotnet publish`), the worker will fail to start unless the matching runtime is installed. Always deploy the published, self-contained worker. ## The schema is empty or out of date The Packaged MA manifest ships with a minimal placeholder schema so MIM can register the agent. Your agent's real schema comes from your `ISchemaProvider` at run time. If MIM is showing an empty or stale schema, run a schema refresh on the management agent so MIM asks your provider for the current schema. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.lithnet.io/ecma2-framework/additional-resources/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.