# How to Troubleshoot Kimi-Code Installation Issues: A Complete Diagnostic Guide

> Troubleshoot Kimi-Code installation issues by verifying Node.js and pnpm versions, running workspace validation, and fixing native binary permissions. Get your Kimi-Code setup right.

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

---

**To troubleshoot Kimi-Code installation issues, verify Node.js ≥24.15.0 and pnpm 10.33.0, run workspace validation scripts to catch configuration drift, and execute permission fixes for native binaries before installing dependencies.**

Kimi-Code is a multi-package TypeScript monorepo maintained by MoonshotAI that relies on a strict toolchain and workspace-synchronization scripts. When you troubleshoot Kimi-Code installation issues, you are typically dealing with one of five failure categories: engine version mismatches, workspace definition drift, missing native binary permissions, broken web asset bundles, or incorrect service naming. Understanding how to diagnose these problems using the repository's built-in validation scripts ensures a clean, reproducible setup.

## Common Installation Failure Categories

### Node Version Mismatch (engine-strict Errors)

The most common blocker is a Node.js version that does not satisfy the `engine` requirements defined in [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json). The repository requires Node ≥24.15.0, specified in `.nvmrc`. If your version is older, `pnpm install` will abort with an `engine-strict` error because `.npmrc` enforces `engine-strict=true`.

Check your environment with:

```bash
node --version  # must be ≥24.15.0

```

### pnpm Version and Package Resolution Errors

Kimi-Code requires pnpm 10.33.0 exactly, declared in the `packageManager` field of [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json). Using a different version can cause lockfile corruption or unexpected package resolution during `pnpm install`.

Verify with:

```bash
pnpm --version  # must be 10.33.0

```

### Workspace Definition Drift (flake.nix vs pnpm-workspace.yaml)

The monorepo uses both [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) for pnpm workspaces and `flake.nix` for Nix builds. If these files drift out of sync, you will encounter missing files in Nix builds or silent import failures. The `scripts/check-nix-workspace.mjs` script validates this synchronization.

### Native Binary Permission Issues (node-pty)

On Linux and macOS, the `node-pty` binary may lose executable permissions during checkout on Windows-derived filesystems. This manifests as "Permission denied" errors. The repository provides `scripts/fix-node-pty-perms.mjs` to restore these bits.

### Missing Web Asset Bundles (dist-web)

If the pre-built web UI bundle is missing from `apps/kimi-code/dist-web/`, the server will fail to start. This typically happens when the repository is cloned without the built assets or when `scripts/check-web-assets.mjs` reports a missing folder.

### Incorrect Service Naming

Services must follow strict naming conventions. Errors complaining about duplicate or malformed names during server startup indicate violations caught by `scripts/check-service-naming.mjs`.

## Step-by-Step Diagnostic Flow

Follow this sequence to identify and resolve installation blockers.

### 1. Verify the Runtime Environment

Ensure your toolchain matches the repository requirements exactly:

```bash
node --version  # → v24.15.0 or higher

pnpm --version  # → 10.33.0

```

If versions are incorrect, install the correct Node version (e.g., `fnm install 24.15.0 && fnm use 24.15.0`) and pnpm 10.33.0.

### 2. Run Workspace Validation Scripts

Execute the built-in checks to catch configuration drift before installing:

```bash
pnpm run check:nix      # executes scripts/check-nix-workspace.mjs

pnpm run check:service  # executes scripts/check-service-naming.mjs

```

These scripts abort early if `flake.nix` and [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) are out of sync or if services have illegal names.

### 3. Patch Native Binary Permissions

On POSIX systems, fix potential permission issues:

```bash
pnpm run fix:pty-perms  # runs scripts/fix-node-pty-perms.mjs

```

This restores executable bits on the `node-pty` binary.

### 4. Install Dependencies

With the environment validated, install dependencies:

```bash
pnpm install

```

Because `engine-strict=true` is set in `.npmrc`, any remaining version mismatches will be flagged instantly.

### 5. Verify Web Assets

If you need the UI, ensure the bundled assets exist:

```bash
pnpm run check:web  # runs scripts/check-web-assets.mjs

```

If the bundle is missing, regenerate it:

```bash
KIMI_CODE_REPO=$(pwd) pnpm -C apps/kimi-code run sync:web

```

### 6. Inspect Build Logs

Run the test suite to surface hidden compilation errors:

```bash
pnpm test

```

The monorepo uses Vite for UI packages and Vitest for tests. Failures often appear as "Failed to resolve entry point" errors in the build output.

### 7. Enable Verbose Logging

If the error remains opaque, enable debug output:

```bash
DEBUG=* pnpm install

```

## Fixing Common Gotchas

**Windows Line Endings Causing Hangs**

If `pnpm install` hangs on Windows, Git for Windows may have converted line endings on `node_modules/.bin` symlinks. Fix this before cloning:

```bash
git config core.autocrlf false

```

**Path Alias Resolution Failures**

"Cannot find module '#/…'" errors occur when the TypeScript path alias `#` defined in [`tsconfig.json`](https://github.com/MoonshotAI/kimi-code/blob/main/tsconfig.json) is not resolved. Ensure you run commands from the repository root or set `NODE_OPTIONS=--require ts-node/register`.

**Missing Pre-Built Web Bundle**

ENOENT errors for [`dist-web/index.html`](https://github.com/MoonshotAI/kimi-code/blob/main/dist-web/index.html) indicate the pre-built bundle was excluded by git-ignore. Either run the `sync:web` command above or disable the server-only mode with `KIMI_CODE_SKIP_WEB=1`.

## Key Configuration Files Reference

Understanding these files helps you troubleshoot Kimi-Code installation issues faster:

- **[`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json)** – Declares Node (`engines`) and pnpm (`packageManager`) requirements
- **`.nvmrc`** – Specifies minimum Node version (24.15.0)
- **`.npmrc`** – Enforces `engine-strict=true`
- **[`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml)** – Defines workspace globs
- **`flake.nix`** – Nix build definition that must stay in sync with the workspace
- **`scripts/check-nix-workspace.mjs`** – Validates workspace sync for Nix builds
- **`scripts/check-service-naming.mjs`** – Enforces service naming conventions
- **`scripts/fix-node-pty-perms.mjs`** – Repairs `node-pty` binary permissions
- **[`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md)** – Authoritative architectural overview and project map

## Summary

- **Verify versions first**: Node must be ≥24.15.0 and pnpm must be 10.33.0 exactly.
- **Run validation scripts**: Execute `pnpm run check:nix` and `pnpm run check:service` to catch configuration drift.
- **Fix permissions**: Run `pnpm run fix:pty-perms` on Linux/macOS after checkout.
- **Check web assets**: If the UI is required, verify `dist-web` exists or run the sync command.
- **Use verbose logging**: Set `DEBUG=*` when errors are cryptic to see internal pnpm steps.

## Frequently Asked Questions

### Why does pnpm install fail with an engine-strict error?

The repository enforces strict engine checks via `.npmrc` with `engine-strict=true`. The [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) specifies Node ≥24.15.0 in the `engines` field. If your Node version is older, pnpm will abort the installation. Check `.nvmrc` for the exact required version and install it before retrying.

### How do I fix permission denied errors on node-pty?

This happens when the `node-pty` native binary loses its executable bit, often due to filesystem differences between Windows and POSIX systems. Run `pnpm run fix:pty-perms`, which executes `scripts/fix-node-pty-perms.mjs` to restore the correct permissions on the binary.

### What should I do if the server cannot find dist-web/index.html?

The pre-built web bundle is excluded from the repository and must be generated locally. Run `KIMI_CODE_REPO=$(pwd) pnpm -C apps/kimi-code run sync:web` to create the `dist-web` folder. Alternatively, set `KIMI_CODE_SKIP_WEB=1` to run in server-only mode if you do not need the UI.

### Why does pnpm install hang on Windows?

This typically occurs when Git for Windows converts line endings on symlinks in `node_modules/.bin`. Run `git config core.autocrlf false` before cloning the repository to prevent automatic CRLF conversion, then delete and re-clone if necessary.