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

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. 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:

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. Using a different version can cause lockfile corruption or unexpected package resolution during pnpm install.

Verify with:

pnpm --version  # must be 10.33.0

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

The monorepo uses both 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:

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:

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 are out of sync or if services have illegal names.

3. Patch Native Binary Permissions

On POSIX systems, fix potential permission issues:

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:

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:

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

If the bundle is missing, regenerate it:

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:

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:

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:

git config core.autocrlf false

Path Alias Resolution Failures

"Cannot find module '#/…'" errors occur when the TypeScript path alias # defined in 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 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 – Declares Node (engines) and pnpm (packageManager) requirements
• .nvmrc – Specifies minimum Node version (24.15.0)
• .npmrc – Enforces engine-strict=true
• 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 – 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 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.

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