# Known Issues with Kimi-CLI: Critical Bugs and Workarounds

> Discover critical bugs in Kimi-CLI, including Windows path issues, env variable errors, and token leaks. Learn about essential workarounds to keep your CLI running smoothly.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: known-issues
- Published: 2026-07-26

---

**Kimi-CLI suffers from Windows path normalization failures, environment variable loading errors, sub-agent race conditions, and MCP authentication token leakage in debug logs.**

Kimi-CLI is a Python-based command-line interface developed by MoonshotAI for interacting with the Kimi AI assistant. While the tool provides powerful async capabilities and sub-agent orchestration, the codebase contains several recurring stability issues that affect Windows users and concurrent workflows. Understanding these known issues with kimi-cli helps developers implement proper safeguards and avoid data corruption in production environments.

## Windows Path Handling Failures

On Windows systems, the path normalization utility fails to handle mixed path separators correctly. When users provide paths containing both forward slashes and backslashes, the [[`windows_paths.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/windows_paths.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/windows_paths.py) module raises `FileNotFoundError` exceptions instead of resolving the file location.

The issue stems from the drive letter normalization logic in [`src/kimi_cli/utils/windows_paths.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/windows_paths.py) not accounting for mixed-separator input received from the UI or shell.

```python
from kimi_cli.utils import windows_paths

# Correct usage to avoid the separator bug

safe_path = windows_paths.normalize(r"C:\Users\Alice\my file.txt")

# Avoid passing raw strings that contain both '/' and '\\'

```

## Environment Variable Loading Errors

The CLI relies on specific environment variables such as `KIMI_NOW`, but the [[`envvar.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/envvar.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/envvar.py) utilities raise generic `KeyError` exceptions when required variables are absent. Rather than aborting with a descriptive message, the CLI often prints warnings and continues execution with undefined or default values, leading to unpredictable behavior.

```python
from kimi_cli.utils import envvar

# Use the safe getter with fallback to prevent KeyError

KIMI_NOW = envvar.get_str("KIMI_NOW", fallback="2024-01-01T00:00:00Z")

```

## Sub-Agent Persistence Race Conditions

When multiple sub-agents resume concurrently, the `SubagentStore` in [[`src/kimi_cli/subagents/store.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/subagents/store.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/subagents/store.py) writes overlapping JSON files. This corruption occurs because the persistence layer lacks file-locking mechanisms during concurrent write operations, causing state data to become interleaved or truncated.

To prevent state corruption, serialize sub-agent creation rather than spawning them simultaneously:

```python

# When spawning multiple sub-agents, serialize their creation

await subagent_store.create_one_by_one([spec1, spec2, spec3])

```

## Async Tool Deadlocks and Dangling Coroutines

The `Toolset` class in [[`src/kimi_cli/soul/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/toolset.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/toolset.py) executes tool calls sequentially but fails to cancel pending async tasks when the main event loop interrupts. This leaves dangling coroutines that consume memory and may block subsequent tool invocations, effectively deadlocking the session.

Always respect cancellation tokens in custom tools to ensure proper cleanup:

```python
async def my_tool(context, cancel_token):
    try:
        await asyncio.wait_for(long_running_op(), timeout=10)
    except asyncio.CancelledError:
        # Clean up resources here before re-raising

        raise

```

## Session Error Recovery and Context Duplication

After exceptions occur, the session recovery logic in [[`src/kimi_cli/session.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/session.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/session.py) attempts to reopen connections but forgets to reset the `Context` checkpoint in [[`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py). This oversight causes duplicated messages to appear in the UI, creating confusion about the actual conversation state and potentially leading to incorrect AI responses based on repeated context.

## Security Vulnerabilities in Logging

Two critical logging issues affect production deployments:

**MCP Token Leakage**: The OAuth flow in [[`src/kimi_cli/mcp_oauth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp_oauth.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp_oauth.py) writes raw authentication tokens to debug logs when `KIMI_DEBUG` is enabled. Third-party log collectors may capture these sensitive credentials, creating a security exposure in centralized logging systems.

```python

# Disable debug logging of sensitive tokens

import os
os.environ["KIMI_DEBUG"] = "0"

```

**Windows Console Encoding**: The `loguru` configuration in [[`src/kimi_cli/utils/logging.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/logging.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/logging.py) uses ANSI color codes that Windows terminals may not interpret correctly, resulting in garbled output or unreadable error messages on older Windows versions.

## Test Suite Flakiness on CI Runners

The end-to-end tests in [`tests_e2e/`](https://github.com/MoonshotAI/kimi-cli/tree/main/tests_e2e), particularly [[`test_wire_real_llm.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/test_wire_real_llm.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/tests_e2e/test_wire_real_llm.py), depend on precise timing for background server initialization. Under heavy CI load, these tests fail intermittently due to race conditions in test setup rather than actual code defects, complicating automated quality assurance.

## Summary

- **Windows path handling** in [`src/kimi_cli/utils/windows_paths.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/windows_paths.py) fails with mixed separators, requiring normalized input strings.
- **Environment variables** without fallbacks in [`src/kimi_cli/utils/envvar.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/envvar.py) cause runtime `KeyError` exceptions.
- **Sub-agent storage** in [`src/kimi_cli/subagents/store.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/subagents/store.py) lacks concurrency controls, necessitating serialized creation to prevent JSON corruption.
- **Async tools** in [`src/kimi_cli/soul/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/toolset.py) may deadlock because the toolset does not cancel pending coroutines on interruption.
- **Session recovery** duplicates messages when [`src/kimi_cli/session.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/session.py) fails to reset [`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py) checkpoints.
- **Security risks** include MCP token exposure in [`src/kimi_cli/mcp_oauth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp_oauth.py) debug logs and Windows console encoding issues in [`src/kimi_cli/utils/logging.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/logging.py).
- **CI stability** suffers from timing-dependent e2e tests in `tests_e2e/` that fail under load.

## Frequently Asked Questions

### How do I fix FileNotFoundError on Windows when using Kimi-CLI?

Ensure all paths passed to the CLI use consistent Windows separators. Use the `windows_paths.normalize()` function from [`src/kimi_cli/utils/windows_paths.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/windows_paths.py) to sanitize user input, and avoid mixing forward and backward slashes in path strings that originate from shell auto-completion or drag-and-drop operations.

### Why does my Kimi-CLI session show duplicate messages after an error?

This occurs because the session recovery logic in [`src/kimi_cli/session.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/session.py) reopens connections without resetting the context checkpoint in [`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py). Restart the CLI completely after critical errors to clear the corrupted state rather than relying on the automatic recovery mechanism.

### Is it safe to enable KIMI_DEBUG in production environments?

No. Enabling `KIMI_DEBUG` causes [`src/kimi_cli/mcp_oauth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp_oauth.py) to write raw OAuth tokens to log files. Always set `KIMI_DEBUG=0` in production to prevent authentication credential leakage through log aggregation systems.

### What causes sub-agent state corruption in concurrent workflows?

The `SubagentStore` class in [`src/kimi_cli/subagents/store.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/subagents/store.py) writes JSON state files without file locking. When multiple sub-agents initialize simultaneously, their write operations overlap. Serialize sub-agent creation using `create_one_by_one()` to avoid this race condition.