mxcli docker run` fails on Mendix 10.x — no alternative path to run the app

[TOFBuck]

Bug: mxcli docker run fails on Mendix 10.x — no alternative path to run the app

Environment

• mxcli version: v0.6.0-dirty (2026-04-09)
• Mendix version: 10.24.x
• Platform: Linux (devcontainer via WSL2)
• Java: OpenJDK Temurin 21

Problem

mxcli docker run does not work with Mendix 10.x projects. The PAD (Portable App Distribution) build target requires Mendix >= 11.6.1, but there is no fallback or alternative for earlier versions.

Steps to reproduce

1. Open any Mendix 10.x project in a devcontainer
2. Run ./mxcli docker run -p app.mpr --wait

Actual result

Error: docker build: portable app distribution requires Mendix >= 11.6.1, found 10.24.x

Expected result

Either:

• mxcli docker run should support Mendix 10.x using the --target=deploy MxBuild approach (MDA/deployment directory) instead of PAD
• Or there should be a clear alternative command (e.g., mxcli run -p app.mpr) that works for Mendix 10.x

Additional issue: Runtime launcher start action fails silently

When trying to manually start the Mendix 10.24 runtime using the launcher JAR, the M2EE admin start action fails with no usable error output.

Steps to reproduce

# Build deployment directory (works fine)
mxbuild --target=deploy --java-home=$JAVA_HOME --java-exe-path=$(which java) app.mpr
# BUILD SUCCEEDED

# Start the runtime launcher (works — admin port responds)
MX_INSTALL_PATH=~/.mxcli/runtime/10.24.x \
M2EE_ADMIN_PASS=<password> \
M2EE_ADMIN_PORT=8090 \
java -jar ~/.mxcli/runtime/10.24.x/runtime/launcher/runtimelauncher.jar ./deployment

# Launcher starts successfully:
# [rtlauncher:container$] INFO Container start took 4831. Ready to accept admin requests.

# Check status (works):
curl -X POST http://localhost:8090/ \
  -H "X-M2EE-Authentication: <base64-encoded-password>" \
  -d '{"action":"runtime_status"}'
# {"feedback":{"status":"feut"},"result":0}

# Start the runtime (FAILS):
curl -X POST http://localhost:8090/ \
  -H "X-M2EE-Authentication: <base64-encoded-password>" \
  -d '{"action":"start","params":{"autocreatedb":true}}'

Actual result

{
  "result": 1,
  "stacktrace": "See logging output for stack trace.",
  "message": "class com.mendix.m2ee.api.internal.AdminException occurred while executing an admin action request. See logging output for details."
}

The logging output is EMPTY. Despite:

• stdout/stderr being redirected to a file (verified via /proc/PID/fd/1)
• MX_LOG_LEVEL=v (verbose) and MX_LOG_LEVEL=d (debug) being set
• The start_logging admin action returning success
• Trying to create log subscribers via the admin API

The Java process produces zero output after the initial container startup lines. The actual error from the start action is completely invisible.

Expected result

The error message from the start action should be:

1. Written to stdout/stderr so it can be captured
2. Or accessible via a log retrieval admin action
3. Or included in the JSON response body (not just "See logging output")

Impact

This makes it impossible to run Mendix 10.x projects via mxcli in a devcontainer, which blocks:

• Automated testing with playwright-cli
• Screenshot generation
• Any browser-based verification workflow

Suggestion

1. Support Mendix 10.x in mxcli docker run using MxBuild --target=deploy + a runtime launcher container
2. Ensure the runtime launcher writes startup errors to stdout
3. Include the actual stack trace in the M2EE admin API error response

[github-actions]

Issue Triage

Summary: The user reports that mxcli docker run fails on Mendix 10.x projects because the PAD build target requires Mendix ≥ 11.6.1, with no fallback to the deploy target or alternative command.

Checklist for bug report completeness:

• [✅] mxcli version
• [✅] Mendix version
• [✅] Scenario (what the user was trying to do)
• [✅] Expected output
• [✅] Experienced output (error message)
• [❌] AI bug report (output of mxcli diag --bundle or session log)

Missing information:
Could you please provide the output of mxcli diag --bundle (or at least the session log) so we can investigate the environment and any underlying issues? Thank you!

---

Automated triage via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Enhancement Request Analysis: mxcli docker run for Mendix 10.x

1. Completeness Assessment

The issue provides sufficient detail for implementation:

• Clear problem statement: mxcli docker run fails on Mendix 10.x due to PAD requiring Mendix >= 11.6.1
• Environment specifics: mxcli v0.6.0-dirty, Mendix 10.24.x, Linux devcontainer, OpenJDK 21
• Reproduction steps: Precise command that fails (./mxcli docker run -p app.mpr --wait)
• Error message: Exact error ("portable app distribution requires Mendix >= 11.6.1, found 10.24.x")
• Expected behavior: Fallback to --target=deploy approach or alternative command
• Additional context: Manual workaround using mxbuild --target=deploy + runtime launcher works

Questions to clarify (minor, implementation can proceed without):

• Should the fallback be automatic (based on detected Mendix version) or require an explicit flag (e.g., --legacy-run)?
• For the deploy target approach, should mxcli handle runtime launcher download/caching automatically (like it does for mxbuild)?
• Should the solution preserve existing --wait behavior and port mapping functionality?

2. Overlap Check

Existing features that partially address this:

• mxbuild --target=deploy command works for Mendix 10.x (verified in issue)
• mxcli setup mxbuild automatically downloads correct mxbuild version for project
• mxcli docker check validates projects but doesn't run them
• mxcli oql queries running runtimes but doesn't start them
• No existing mxcli run command or deploy-target-based docker execution

Gap: No integrated path from mxcli docker run to traditional deployment directory approach for Mendix < 11.6.1.

3. Proposed MDL Syntax

This enhancement concerns CLI behavior, not MDL syntax. However, interpreting "syntax" as CLI command behavior:

Current behavior (fails for Mendix < 11.6.1):

mxcli docker run -p app.mpr --wait  # Uses PAD target internally

Proposed behavior (automatic fallback):

# For Mendix >= 11.6.1: Uses existing PAD approach (unchanged)
mxcli docker run -p app.mpr --wait

# For Mendix < 11.6.1: Automatically falls back to deploy target approach
mxcli docker run -p app.mpr --wait  # Same command, different internal path

Alternative explicit approach (if preferred):

mxcli docker run -p app.mpr --target=deploy --wait  # Explicit legacy mode
mxcli docker run -p app.mpr --target=pad --wait     # Explicit PAD mode (current default)

Evaluation against guidelines:

• ✅ Reads as English: "docker run" implies running the app
• ✅ Follows standard patterns: Uses existing --target pattern from mxbuild
• ✅ Qualified names: Not applicable (CLI flags)
• ✅ Diff-friendly: Adding --target=deploy is one-line change
• ⚠️ LLM-friendly: Automatic fallback requires no user action (better for LLMs)
• ❌ One way to do each thing: Two paths exist (but fallback is transparent)

Recommendation: Implement automatic version detection with fallback to deploy target for Mendix < 11.6.1. This preserves UX while solving the core issue.

4. Implementation Roadmap

Focus on modifying the docker run command logic to detect Mendix version and choose appropriate build target.

Files to modify:

1. cmd/mxcli/docker/run.go - Main docker run command implementation
2. cmd/mxcli/docker/build.go - May need to share version detection logic
3. cmd/mxcli/setup_mxbuild.go - Reuse existing mxbuild setup logic
4. cmd/mxcli/docker/util.go - New helper for version-aware docker operations

Step-by-step checklist:

• Version detection: Add function to get Mendix version from .mpr file (reuse existing logic from setup mxbuild)
  • Reference: cmd/mxcli/setup_mxbuild.go:getMendixVersionFromProject()
• Version comparison: Implement semantic version check (>= 11.6.1 vs < 11.6.1)
  • Reference: github.com/hashicorp/go-version likely already used elsewhere
• Modify docker run flow:
  • For Mendix >= 11.6.1: Keep existing PAD path (mxbuild --target=pad + patching)
  • For Mendix < 11.6.1: New deploy target path:
    1. Ensure mxbuild is available for project's version (mxcli setup mxbuild -p app.mpr)
    2. Run mxbuild --target=deploy --java-home=$JAVA_HOME --java-exe-path=$(which java) app.mpr
    3. Generate Dockerfile that:
       • Uses openjdk:21-jre-slim base (matching user's environment)
       • Sets MX_INSTALL_PATH to downloaded runtime location
       • Copies deployment directory to /app/deployment
       • Sets M2EE_ADMIN_PASS and M2EE_ADMIN_PORT from env/defaults
       • Entry point: java -jar $MX_INSTALL_PATH/runtime/launcher/runtimelauncher.jar /app/deployment
    4. Build and run container with port mapping/wait logic
• Runtime handling:
  • Reuse existing runtime download/caching logic from mxcli setup mxbuild or similar
  • Reference: How mxcli currently handles runtime JARs for OQL/etc.
• Environment variable propagation:
  • Allow M2EE_ADMIN_PASS/M2EE_ADMIN_PORT to be passed via --build-arg or env
  • Default to generating random password if not provided (matching current PAD behavior)
• Wait logic preservation:
  • Keep existing --wait functionality using M2EE admin API polling
  • Reference: cmd/mxcli/docker/oql.go for admin API interaction

Patterns to follow:

• Use existing mxcli setup mxbuild pattern for version-specific tooling
• Reuse Dockerfile generation patterns from current PAD implementation
• Follow error handling patterns in cmd/mxcli/docker/ (wrap errors with context)
• Maintain backward compatibility - no breaking changes to existing flags

5. BSON Investigation

Not directly applicable - this enhancement concerns build/runtime execution, not MDL/BSON manipulation. However, for completeness:

Relevant BSON aspects (for context only):

• Mendix version is stored in MPR file (likely in System$Version or similar)
• To investigate:

  mxcli bson dump -p app.mpr --type System --object Version

• But version detection should reuse existing logic from setup mxbuild command rather than re-implementing BSON parsing

Investigation steps (if needed):

1. Check how mxcli setup mxbuild determines project version
2. Verify this works for both MPR v1 (SQLite) and v2 (metadata + mprcontents/)
3. Ensure version parsing handles Mendix 10.x.y format correctly

6. Testing Strategy

Doctype test script (mdl-examples/doctype-tests/):

• Not applicable (CLI/docker feature), but add verification steps to:
  • mdl-examples/doctype-tests/00-commands.mdl (if exists) or create new docker-specific test

mxcli validations to expect:

• mxcli docker run -p mendix10_project.mpr --wait should:
  • Succeed for Mendix 10.x project (builds deploy target, starts container)
  • Fail gracefully for invalid projects (show mxbuild errors)
  • Respect --wait timeout and port mapping (-p 8080:8080)
  • Contain app in container logs (verify via docker logs)

Integration tests:

1. Version matrix testing:
   • Mendix 9.x: Should use deploy target path
   • Mendix 10.x: Should use deploy target path
   • Mendix 11.0-11.5: Should use deploy target path
   • Mendix 11.6.1+: Should use PAD path (existing behavior)
2. Functional verification:
   • After mxcli docker run --wait, curl http://localhost:8080 should return Mendix login page
   • mxcli oql -p app.mpr "SELECT COUNT(*) FROM MyModule.Entity" should work
   • mxcli docker stop should cleanly terminate container
3. Edge cases:
   • Missing Java: Should show clear error about JAVA_HOME/java.exe
   • Invalid project: Should propagate mxbuild errors
   • Concurrent runs: Should handle port conflicts gracefully

7. Gotchas & Risks

Common pitfalls for this type of feature:

• Version detection errors:
  • Mendix version string format varies (10.24.0 vs 10.24.0.12345)
  • Solution: Use semantic version library, compare only major.minor.patch
• Runtime path handling:
  • MX_INSTALL_PATH must point to extracted runtime (not just downloaded archive)
  • Solution: Reuse existing runtime extraction logic from mxcli's setup commands
• Java executable resolution:
  • User may have JAVA_HOME set but java.exe not in PATH
  • Solution: Check both $JAVA_HOME/bin/java and $(which java) like user's manual workaround
• Admin password management:
  • PAD approach auto-generates password; deploy target needs explicit handling
  • Solution:
    • If M2EE_ADMIN_PASS not set, generate random password
    • Pass to container via -e flag
    • Output password to stdout (like current PAD behavior) for user to capture
• Logging visibility (addresses secondary issue):
  • Runtime launcher may still fail silently, but mxcli can:
    • Capture container stdout/stderr and relay to user
    • Add --logs flag to stream runtime launcher logs
    • Note: True fix requires Mendix runtime changes, but mxcli can improve visibility
• Base image selection:
  • Must match Java version used by mxbuild (OpenJDK 21 for Mendix 10.24.x)
  • Solution: Derive base image from Java version used in mxbuild command
• Windows/Linux path issues:
  • mxbuild paths may differ in devcontainer (WSL2) vs native
  • Solution: Use absolute paths, test in Linux container environment

Critical risk: If the runtime launcher's silent failure issue (secondary problem) persists in the deploy target approach, users may still see "started" but app not actually running. Mitigation:

• Extend --wait logic to not just check container status, but verify app is responding (e.g., curl -f http://localhost:8080/login)
• Add health check to Dockerfile: HEALTHCHECK CMD curl -f http://localhost:8080/login || exit 1
• Improve error messaging if health check fails after start

Recommendation: Implement the deploy target fallback as primary solution for Mendix 10.x. The silent launcher issue is likely a Mendix runtime bug outside mxcli's scope, but mxcli can improve diagnostics by capturing and forwarding container logs.

---

Automated guide via OpenRouter — workflow source