feat(diagnostics): make MCPX_DOCKER_EXEC_NOT_FOUND runtime-aware (MCP-2909)#720
Conversation
The static DockerExecNotFound catalog message ("the image has no
uvx/node") is too generic to self-resolve. A field report (ElevenLabs /
uvx) hit it because of a per-server `isolation.image: "python:3.11"`
override — stock python has no uvx — but the owner misattributed it to
recent host-side docker PATH fixes.
Enrich the remediation with per-server context: name the detected
runtime (uvx/npx/pipx/…), the recommended runtime-default image
(default_images[runtimeType]), and flag a per-server isolation.image
override as the likely culprit when it differs from the default.
- ClassifierHints gains DockerCommand / DockerImageOverride /
DockerDefaultImages (diagnostics-only; never affect classification).
- RuntimeAwareRemediation(code, hints) builds the enriched message;
DiagnosticError.Remediation carries it; the REST/status serializers
prefer it over the static UserMessage when present.
- detectDockerRuntimeType mirrors core.DetectRuntimeType for display
(diagnostics must not import upstream/core).
- Add docs/errors/MCPX_DOCKER_EXEC_NOT_FOUND.md + README index entry.
Image selection and TransformCommandForContainer are unchanged
(correct since #477) — this is diagnostics-only.
Related MCP-2909
Deploying mcpproxy-docs with
|
| Latest commit: |
99ce599
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://1e834ce8.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://fix-mcp-2909-docker-exec-run.mcpproxy-docs.pages.dev |
…D page Docusaurus broken-links check failed the docs build: ../docker-isolation.md resolved to /docker-isolation.md (no such route). Use ../features/docker-isolation.md, matching the sibling MCPX_DOCKER_IMAGE_PULL_FAILED page. Related MCP-2909
|
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 27804766378 --repo smart-mcp-proxy/mcpproxy-go
|
![mcpproxy-gatekeeper[bot]](https://avatars.githubusercontent.com/u/216428285?s=60&v=4){kind=small}
There was a problem hiding this comment.
APPROVE — reviewed via Claude Code. Runtime-aware remediation message for existing MCPX_DOCKER_EXEC_NOT_FOUND; classifier UNCHANGED (no new/over-broad string-matching — per repo caveat), display-layer only, gated on code+DockerCommand!='' and fully nil-safe (supervisor hint chain guards srv/Isolation/snap.Config). Both render sites consistent; Remediation JSON omitempty (back-compat). go build clean, diagnostics+runtime tests pass (4 new subtests); internal/server FAILs are pre-existing E2E binary-path env, not this diff. MCP-2849.
2 participants
Summary
Makes the
MCPX_DOCKER_EXEC_NOT_FOUNDdiagnostic runtime-aware so a user can self-resolve it.A field report (ElevenLabs upstream,
uvxruntime) hit this code because of a per-serverisolation.image: "python:3.11"override — stockpython:3.11has nouvx(uv is a separate Astral tool), sodocker run python:3.11 uvx …fails at exec time inside the container. The system behaved correctly, but the owner misattributed it to recent host-side docker PATH fixes (#697/#703/#714/#716/#717). That misdiagnosis is the signal: the static catalog message ("the image has nouvx/node") is too generic.What changed (diagnostics-only)
ClassifierHintsgainsDockerCommand,DockerImageOverride,DockerDefaultImages. These are diagnostics-only — they never affect classification, only the user-facing message.RuntimeAwareRemediation(code, hints)(new,internal/diagnostics/remediation.go) builds an enriched message forDockerExecNotFoundthat names:uvx/npx/pipx/…),default_images[runtimeType]),isolation.imageoverride as the likely culprit when it differs from the runtime default.DiagnosticError.Remediationcarries the enriched string; the REST (internal/server/server.go) and status (internal/runtime/runtime.go) serializers prefer it over the staticUserMessagewhen present.classifierHints) populates the new hints from the server config + globaldefault_imagesfor Docker-isolated servers.detectDockerRuntimeTypeis a small, side-effect-free mirror ofcore.DetectRuntimeType(the diagnostics package must not importupstream/core; same precedent assupervisor.usesDockerIsolationmirroringShouldIsolate).docs/errors/MCPX_DOCKER_EXEC_NOT_FOUND.md+ README index entry (thedocsURLtarget previously 404'd).Out of scope (per issue): image selection and
TransformCommandForContainerare unchanged (correct since #477). A config-save/connect-time warning for override mismatch was declined by the owner.Example enriched message
Testing (TDD)
internal/diagnostics/classifier_domains_test.go: newTestRuntimeAwareRemediation_DockerExecNotFound(uvx-on-bare-python override, npx-no-override, no-command fallback, other-code no-op). Written failing first, then implemented.go build ./...,go test ./internal/diagnostics/... ./internal/runtime/supervisor/... -racegreen.golangci-lint(v2,.github/.golangci.yml) on touched packages: 0 issues.Related MCP-2909