# How to Debug Issues Within kimi-code Applications: Complete Developer Guide

> Debug kimi-code applications effectively. Expose internal state, inspect transport errors, and capture TUI render cycles with this complete developer guide. Troubleshoot with ease.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Enable the debug RPC surface with `--debug-endpoints` bound to `127.0.0.1` to expose internal service state via `/api/v1/debug`, inspect transport errors in [`errors.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/errors.ts), and capture TUI render cycles using `PI_DEBUG_REDRAW=1` for comprehensive troubleshooting.**

Debugging issues within kimi-code applications requires navigating its TypeScript monorepo architecture, where a local **kap-server** engine powers multiple front-ends including CLI, TUI, and VS Code extensions. The repository exposes a reflection-based debug RPC layer that provides unrestricted visibility into the dependency injection (DI) container when activated on loopback interfaces, allowing you to query live service states without modifying source code.

## Enable the Debug RPC Surface

The debug functionality is gated behind runtime flags to prevent accidental exposure on public networks. When starting the server via `pnpm dev:v2` or programmatically, you must explicitly activate the endpoints and ensure the host resolves as loopback.

Start the server with the required flags:

```bash
node ./packages/kap-server/src/start.ts --debug-endpoints --host 127.0.0.1

```

The `--debug-endpoints` flag triggers the `debugEndpoints` option in `ServerStartOptions` as defined in [`packages/kap-server/src/start.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/start.ts) (lines 101‑102). The server performs a security check via `classify` in [`security/bindClassify.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/security/bindClassify.ts) to verify the bind address qualifies as loopback; debug endpoints remain disabled on non-loopback interfaces.

To enable debugging programmatically from another process (such as the CLI), pass the option to `startServer`:

```typescript
import { startServer } from '@moonshot-ai/kap-server';

await startServer({ debugEndpoints: true, host: '127.0.0.1' });

```

## Query Services via the Debug HTTP API

Once enabled, the server mounts a reflection-based RPC dispatcher under `/api/v1/debug`. This surface is registered by [`registerDebugRoutes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/registerDebugRoutes.ts) (lines 22‑27), which delegates to the generic dispatcher in [`serviceDispatcherRoutes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/serviceDispatcherRoutes.ts) (lines 17‑27).

### List Available Channels

Discover all exposed services and their methods by querying the channels endpoint:

```bash
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:58627/api/v1/debug/channels

```

The response returns a JSON array of channel descriptors containing service IDs, scopes, and available methods. The **kimi-inspect** UI consumes this same data to build its service explorer.

### Invoke Service Methods

Target any DI-registered service by constructing the path `/api/v1/debug/<ServiceId>/<method>`. The dispatcher resolves the service at runtime via `resolveAnyScopedServiceId` in [`packages/kap-server/src/transport/channelRegistry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/transport/channelRegistry.ts) (lines 19‑25).

For example, to flush the in-memory append-log store (`IAppendLogStore`):

```typescript
import fetch from 'node-fetch';

const token = process.env.KIMI_TOKEN;
const resp = await fetch(
  'http://127.0.0.1:58627/api/v1/debug/IAppendLogStore/flush',
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify([]),
  },
);
const { data } = await resp.json();
console.log(data);

```

### Extract Service State Snapshots

Fetch structured internal state from any service to verify runtime values:

```typescript
async function getServiceState(token: string, serviceId: string) {
  const url = `http://127.0.0.1:58627/api/v1/debug/${serviceId}/snapshot`;
  const resp = await fetch(url, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify([]),
  });
  if (!resp.ok) throw new Error(`Debug call failed: ${resp.status}`);
  const { data } = await resp.json();
  return data;
}

// Usage example:
const state = await getServiceState(token, 'ISessionIndex');
console.log(JSON.stringify(state, null, 2));

```

## Diagnose Transport-Level Errors

When services throw exceptions, the RPC layer translates them into structured `TransportError` responses. The mapping logic resides in [`packages/kap-server/src/transport/errors.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/transport/errors.ts).

If you receive 500-level responses, examine the `code` and `msg` fields in the error payload. This correlation helps determine whether failures originate from service implementation logic, DI container resolution, or downstream providers.

## Debug the Terminal UI Interactively

The `pi-tui` package provides runtime introspection tools for UI-related issues.

Press **Shift+Ctrl+D** to trigger the debug callback defined in [`packages/pi-tui/src/tui.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/tui.ts) (lines 327‑334). Additionally, set the environment variable `PI_DEBUG_REDRAW=1` before launching the TUI to enable render-cycle dumps:

```bash
export PI_DEBUG_REDRAW=1
pnpm dev:tui

# Press Shift+Ctrl+D in the UI to dump state

```

When enabled, the TUI writes rendering data to `/tmp/tui/render-<timestamp>.log` (see the `debugDir` logic around line 1609). Diff these logs to trace how component trees change across state updates.

## Leverage Test Helpers for Reproduction

The test suite contains helpers that instantiate real servers with debug RPC enabled. Reference [`packages/kap-server/test/debugNonloopback.e2e.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/test/debugNonloopback.e2e.test.ts) for a minimal example that validates endpoint security.

Use this pattern to spin up temporary debug servers in custom scripts:

```typescript
import { startServer } from '@moonshot-ai/kap-server';

const server = await startServer({ 
  host: '127.0.0.1', 
  debugEndpoints: true 
});
// Server is now accessible for curl-based debugging

```

## Common Debug Scenarios

### Service Not Found Errors

Query `/api/v1/debug/channels` to verify the service ID is registered. If absent, ensure the package containing the service is imported in the server bootstrap sequence (check `bootstrap` seeds in [`start.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/start.ts)).

### Authentication Failures (401)

Confirm the bearer token matches the persistent token printed on server startup, or supply the optional `rpcToken` if you configured custom authentication.

### Unexpected Transcript State

Use the `/api/v1/debug/transcript/...` endpoints to fetch raw operation logs and compare them against UI representations.

### Debug RPC Unavailable

Verify the server started with both `--debug-endpoints` and a loopback address (`127.0.0.1`). The framework silently disables debug surfaces on non-loopback binds for security.

## Summary

- Activate the debug surface with `--debug-endpoints` and loopback binding to safely expose internal services.
- Query `/api/v1/debug/channels` to discover all injectable services, then invoke methods via `/api/v1/debug/<Service>/<method>`.
- Interpret transport errors using the mapper in [`packages/kap-server/src/transport/errors.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/transport/errors.ts).
- Capture TUI render states by setting `PI_DEBUG_REDRAW=1` and triggering dumps with Shift+Ctrl+D.
- Use test helpers from [`debugNonloopback.e2e.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/debugNonloopback.e2e.test.ts) to create reproducible debug environments.

## Frequently Asked Questions

### How do I enable debug endpoints in kimi-code?

Start the server with the `--debug-endpoints` flag and bind to `127.0.0.1` to satisfy the loopback security check defined in [`security/bindClassify.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/security/bindClassify.ts). Programmatically, pass `debugEndpoints: true` to the `startServer` options in [`packages/kap-server/src/start.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/start.ts).

### Why is the debug RPC returning 401 Unauthorized?

The bearer token in your request headers must match the persistent token printed during server startup, or the custom `rpcToken` configured in server options. Verify the `Authorization: Bearer <token>` header format and ensure the token has not expired.

### How can I inspect the TUI render state for visual bugs?

Set the environment variable `PI_DEBUG_REDRAW=1` before launching the TUI, then press **Shift+Ctrl+D** to trigger a dump. The framework writes component tree data to `/tmp/tui/render-<timestamp>.log` according to the logic in [`packages/pi-tui/src/tui.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/tui.ts), allowing offline inspection of rendering cycles.

### What should I check if a service method returns 404?

First, query `/api/v1/debug/channels` to confirm the service ID is registered in the DI container. If the service is missing, check that its package is properly imported in the server bootstrap. Also verify the method name spelling matches the exposed interface, as the dispatcher in [`serviceDispatcherRoutes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/serviceDispatcherRoutes.ts) performs exact string matching.