# How to Troubleshoot Apache Maka Issues: A Complete Diagnostic Guide

> Troubleshoot Apache Maka issues with our complete diagnostic guide. Learn to fix version mismatches, WebSocket connectivity, and missing Docker images using built-in commands.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), 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](https://github.com/apache/maka/blob/main/docs/runtime-host-remote-access.md), 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](https://github.com/apache/maka/blob/main/packages/eval/README.md) 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](https://github.com/apache/maka/blob/main/docs/windows-support.md) 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:

```bash

# 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](https://github.com/apache/maka/blob/main/packages/cli/README.md), 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](https://github.com/apache/maka/blob/main/docs/windows-support.md). 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.