Troubleshooting (.NET)

View as MarkdownMarkdown

Set up your AI agent

Give your coding agent live access to the GroupDocs documentation and API reference through the GroupDocs Docs MCP server — no install, no API key. Learn more

claude mcp add --transport http groupdocs-docs https://docs.groupdocs.com/mcp

Also process documents locally

The GroupDocs.Merger MCP server lets your agent work with files on your machine; they are never uploaded. It needs the .NET 10 SDK or Docker.

claude mcp add groupdocs-merger -- dnx GroupDocs.Merger.Mcp --yes
Folders, licensing and more →

Problems that only affect the .NET build of the server — the dnx runner, its native dependencies, and the Docker channel. For issues that are the same on every platform (the server not appearing in your client, evaluation limits, engine behaviour), see Troubleshooting & FAQ.

dnx command not found

The dnx runner ships inside the .NET 10 SDK — it is not a separate download. Install the .NET 10 SDK (the setup/<os> bootstrapper in the installer does it for you), then open a new terminal so PATH refreshes.

  • Windows: C:\Program Files\dotnet\dnx.cmd
  • Linux / macOS: dnx next to the dotnet binary

Check with dotnet --version (expect 10.x) and dnx --help.

Note
Your AI client has its own PATH, which may differ from your terminal’s — a GUI client launched from the desktop often does not see a PATH set in your shell profile. If dnx works in the terminal but the client reports it missing, that mismatch is the reason; use an absolute command path in the client entry, or launch the client from a terminal.

DllNotFoundException: libgdiplus

On Linux and macOS in the NuGet channel, the engine needs native graphics libraries that are not installed by default:

# Linux (Debian/Ubuntu)
sudo apt-get install -y --no-install-recommends \
  libgdiplus libfontconfig1
# macOS
brew install mono-libgdiplus

Or switch to the Docker channel, where every native dependency is already inside the image — this is why Docker is the recommended default on Linux and macOS. See Install on Linux / Install on macOS.

Permission denied when saving into a mounted folder (Docker on Linux)

The image runs as a non-root user (uid 1654) and a mounted folder keeps its host owner, so the container cannot write into a folder you own. Run it as you: --user "$(id -u):$(id -g)" on the command line, or "--user", "1000:1000" (your id -u and id -g) in a JSON client config, which runs no shell.

The first tool call is slow, or fails once and then works

A cold cache: on first use dnx downloads the package (or Docker pulls the image) while your client is already waiting on the connection. Warm it once:

./install-groupdocs-mcp.ps1 -Prewarm

Or run the launch command yourself once in a terminal — dnx GroupDocs.Merger.Mcp --yes, or docker pull ghcr.io/groupdocs-merger/merger-net-mcp:latest. The installer’s -Verify mode pre-warms automatically.

“docker daemon not reachable”

Start Docker Desktop (or dockerd). The installer’s preflight detects this before writing any config and prints the exact setup/<os> command that fixes the environment.

Pinning a version

dnx GroupDocs.Merger.Mcp --yes resolves the latest stable release on every launch. For shared or committed configurations, pin it — dnx GroupDocs.Merger.Mcp@26.9.0 --yes, or the image tag :26.9.0 instead of :latest.

Verifying an installation end-to-end

./verify-groupdocs-mcp.ps1

Performs the real MCP handshake per configured product and — when a document exists in your storage folder — a live get_document_info call through the engine. Exit 0 = healthy; failures print the server’s own error text.

Still stuck?

Post your config (redact license paths) and the client name in the Merger forum. Bugs: GitHub issues.