How to Troubleshoot Apache Maka Issues: A Complete Diagnostic Guide

Apache Maka issues typically stem from version mismatches between the CLI and runtime host, WebSocket connectivity blocked by firewalls, or missing Docker images for the evaluation harness, all of which can be diagnosed using built-in logging and dependency check commands.

Apache Maka is a modular, multi-runtime AI-assistant platform composed of a CLI (@maka/cli), a runtime host (@maka/runtime-host), and an evaluation engine (@maka/eval). When agents fail to execute or connections drop unexpectedly, understanding how to troubleshoot Apache Maka issues requires inspecting the interaction boundaries between these components. The monorepo structure defines clear separation of concerns, with each package exposing specific diagnostic surfaces documented in the source.

Understanding the Apache Maka Architecture

Before debugging, map your issue to the correct component boundary. According to the Architecture guide, the platform consists of four primary surfaces:

• CLI (@maka/cli): Launches local or remote runtime hosts and manages agent deployments.
• Runtime Host (@maka/runtime-host): Provides sandboxed execution environments for agents via WebSocket connections.
• Eval Package (@maka/eval): Executes test suites against agents using a relay protocol, typically containerized via Docker.
• Desktop Client: Communicates with the runtime host over WebSocket for UI interactions.

Isolation failures usually occur at the network boundary between the desktop client and runtime host, or within the Docker sandbox used by the evaluation harness.

Common Failure Surfaces

Runtime Host Connectivity Issues

The desktop client contacts the runtime host over a WebSocket connection, typically on port 8080. Connection failures manifest as timeout errors or TLS handshake exceptions. Per the runtime-host remote-access documentation, verify that:

• Firewall rules allow outbound connections to the host.
• TLS certificates are present and valid if using remote access.
• The host process is listening on the expected interface (check ~/.maka/runtime-host/logs/*.log for "connection refused" entries).

Evaluation Harness Errors

The @maka/eval package requires Docker or a local sandbox to execute test agents. Common errors include "subject not found" or "executor crash," indicating missing Docker images or insufficient sandbox permissions. The Eval README specifies that the maka-eval-harness container must be running before executing suites.

Windows-Specific Dependency Problems

Windows users running the portable binary (Maka-<version>-win-x64.exe) may encounter missing runtime libraries. The Windows support guide requires the portable ZIP to contain ffmpeg.exe and node.exe alongside the main executable. Use the built-in dependency checker to validate the environment.

Step-by-Step Troubleshooting Workflow

Follow this sequence to isolate the failure domain:

1. Verify Version Alignment
   Run maka --version to confirm the CLI matches the runtime-host version. Mismatched versions between @maka/cli and @maka/runtime-host cause protocol incompatibilities that surface as silent connection failures.

2. Inspect Host Logs
   Examine ~/.maka/runtime-host/logs/*.log for TLS errors or bind failures. Look specifically for "EADDRINUSE" if port 8080 is occupied by another process.

3. Validate Network Ports
   Ensure port 8080 (or your configured port) is open and unblocked by OS firewalls. On remote hosts, verify security groups allow ingress on the WebSocket port.

4. Confirm Docker Containers
   For evaluation failures, run docker ps and verify the maka-eval-harness container is in "Up" state. If missing, rebuild the image from packages/eval and check for exit code 137 (out-of-memory kills).

5. Audit Windows Dependencies
   On Windows, execute .\Maka-<version>-win-x64.exe --check-deps from PowerShell. This validates the presence of ffmpeg.exe and node.exe in the application directory.

6. Capture Verbose Output
   Reproduce the issue with debug logging enabled: maka --log debug. Redirect output to a file and attach it when opening a GitHub issue.

Essential Diagnostic Commands

Use these commands to extract runtime state:

# Display installed component versions

maka --version

# Start the runtime host with debug-level logging

maka-runtime-host --debug

# List active evaluation containers

docker ps --filter "name=maka-eval"

# Check runtime host health and connectivity

maka runtime-host status

# Tail recent host logs without opening the file directly

maka runtime-host logs --tail 50

# Execute the built-in smoke test suite locally

cd packages/eval
npm run build
maka eval run --suite smoke-tests

# Enable debug mode for desktop client UI interactions

maka desktop --log debug

# Verify Windows portable binary dependencies (PowerShell)

.\Maka-1.2.0-win-x64.exe --check-deps

When to Escalate to GitHub Issues

Escalate to the Apache Maka repository after completing the workflow above if you encounter:

• Repeated TLS handshake failures despite valid certificates and clock synchronization.
• Docker container crashes with exit code 137, indicating memory limits exceeded by the evaluation harness.
• Unexpected host exits on macOS or Linux immediately following an OS kernel upgrade.

When reporting, include the output of maka --version, relevant log excerpts from ~/.maka/runtime-host/logs/, and a minimal reproducible configuration.

Summary

• Version parity between @maka/cli and @maka/runtime-host prevents protocol-level connection failures.
• Log inspection at ~/.maka/runtime-host/logs/*.log reveals TLS and port-binding errors.
• Docker validation using docker ps confirms the evaluation harness is operational before running test suites.
• Windows dependency checks via --check-deps ensure ffmpeg.exe and node.exe are present in portable builds.
• Debug logging (--log debug) provides the necessary verbosity for GitHub issue escalations.

Frequently Asked Questions

How do I check if my CLI version is compatible with the runtime host?

Run maka --version and compare the output against the runtime host's reported version in its startup logs. According to the CLI documentation, major version mismatches will trigger a warning, but patch differences may cause subtle WebSocket protocol errors.

Why does the evaluation harness fail with "subject not found" errors?

This error indicates the @maka/eval package cannot locate the agent executable within the Docker sandbox. Confirm the maka-eval-harness container is running via docker ps, and rebuild the evaluation package with npm run build in packages/eval to ensure the test subject is bundled correctly.

How can I verify Windows portable binary dependencies?

Execute .\Maka-<version>-win-x64.exe --check-deps in PowerShell. The command validates that ffmpeg.exe and node.exe exist in the application directory as required by the Windows support documentation. Missing files must be extracted from the original portable ZIP distribution.

Where are the runtime host logs stored on macOS and Linux?

Runtime host logs are written to ~/.maka/runtime-host/logs/*.log on Unix-like systems. Use maka runtime-host logs --tail 50 to view recent entries without manually navigating the directory, or inspect the files directly to diagnose TLS certificate errors and port conflicts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}