How to Debug File Permission and Path Access Policy Issues in Kimi Code

To debug permission errors in Kimi Code, verify the session's permission mode (manual/yolo/auto), check for the specific error code fs.permission_denied (40411), and ensure underlying OS-level file system permissions allow access for the process user.

Kimi Code, the open-source agent framework from MoonshotAI, enforces a strict permission model that governs how agents interact with the file system. When you encounter "permission denied" errors, the issue typically stems from one of three layers: the session's permission mode configuration, OS-level access controls, or the protocol's error mapping system. Understanding how these layers interact allows you to systematically resolve access issues without guesswork.

Understanding Kimi Code's Permission Architecture

Kimi Code implements a fine-grained permission system that operates at both the session configuration level and the protocol event level. Errors are not generic; they flow through a specific pipeline that maps OS-level denials to canonical protocol codes.

Permission Modes

Kimi Code supports three distinct permission modes defined in packages/protocol/src/rest/prompt.ts:

• Manual – The user must explicitly approve every file operation before execution.
• Yolo – The agent may read or write without prompting, but still respects OS-level restrictions.
• Auto – The system decides based on context and prior approvals.

These modes are controlled via the permission_mode field in session-update payloads and can be changed at runtime using the permission.set_mode event.

Session-Level Configuration

When a session initializes, the SDK reads the optional default_permission_mode from the user's config.toml. If absent, the server falls back to auto. This behavior is verified in packages/node-sdk/test/create-session-transport.test.ts, which confirms the default is applied when no explicit configuration exists.

You can query the current permission state at any time using session.getStatus(), which returns a SessionStatus object containing the permission property.

Tracing the File System Error Flow

When an operation fails, the error propagates through several layers before reaching your client code. Understanding this flow helps pinpoint whether the denial originates from Kimi Code's policy layer or the operating system.

The mapping follows this path:

1. OS Interface – Located in packages/agent-core-v2/src/os/interface/hostFsErrors.ts, this layer maps raw OS errors like EACCES and EPERM to the canonical error code fs.permission_denied.
2. Kap-Server Routes – In packages/kap-server/src/routes/workspaceFs.ts, the mapped error triggers an HTTP 404 response with code 40411.
3. Protocol Events – packages/protocol/src/events.ts declares the event name 'fs.permission_denied' (lines 296-309), ensuring consistent handling across SDKs.
4. Client-Side – The SDK translates the HTTP response into a typed error with code ErrorCode.FS_PERMISSION_DENIED.

These layers are linked by Zod schemas, including permissionModeSchema for modes and the ErrorCode enum for error classification.

Step-by-Step Debugging Workflow

Follow this systematic approach to isolate and resolve permission issues.

1. Confirm the Session Permission Mode

Start by verifying the active permission mode for your session. If the mode is manual and you expected automatic access, the agent is waiting for explicit approval.

const sess = await client.createSession({ id: 'my-sess', workDir });
const status = await sess.getStatus();
console.log('Permission mode:', status.permission);   // manual | yolo | auto

// Change to auto mode if needed
await sess.sendEvent('permission.set_mode', { mode: 'auto' });

2. Check OS-Level File System Permissions

Kimi Code does not elevate privileges. Use standard OS tools (ls -l, stat, or icacls) to verify that the process user has read or write access to the target path. If the OS denies access, Kimi Code will report the failure regardless of the session's permission mode.

3. Inspect the Exact Error Code

Capture the typed error thrown by the SDK to determine if the denial originates from Kimi Code's policy layer or the OS:

try {
  await sess.readFile('/restricted/path.txt');
} catch (e) {
  if (e.code === 'fs.permission_denied') {
    console.error('Kimi Code policy or OS denies access');
  }
}

The code fs.permission_denied (40411) indicates a mapped permission failure from any layer in the stack.

4. Review config.toml for Default Mode

A missing or mis-typed default_permission_mode entry can cause sessions to start in manual mode unexpectedly. Verify your configuration file contains a valid entry:

default_permission_mode = "auto"

Valid values are strictly manual, yolo, or auto.

5. Enable Verbose Logging

Run the server with the --debug-endpoints flag to expose the raw event stream. The debug UI in apps/kimi-inspect (connected via vite/serverDiscovery.ts) displays events including permission.set_mode and fs.permission_denied, allowing you to pinpoint which request triggered the failure in real-time.

Common Pitfalls and Solutions

Symptom	Root Cause	Fix
"Permission denied" on owned files	Session is in manual mode awaiting approval	Switch to auto mode or approve the pending operation
Error persists after switching mode	OS ACL denies the process user	Adjust OS permissions or run the server under a user with required rights
Permission mode changes do not persist	Outdated SDK version	Upgrade to the latest @moonshot-ai/kimi-code-sdk
Access denied for paths outside workspace	Workspace sandbox restriction	Place files inside the session's workDir or configure a broader workspace root

Summary

• Kimi Code uses three permission modes (manual, yolo, auto) configured via config.toml or runtime events.
• Permission errors flow from OS → hostFsErrors.ts → workspaceFs.ts → protocol event fs.permission_denied (40411).
• Always verify both the session's permission_mode and underlying OS file system permissions.
• Use session.getStatus() to inspect current permissions and sendEvent('permission.set_mode') to change them dynamically.
• Enable --debug-endpoints and use apps/kimi-inspect to trace permission events in real-time.

Frequently Asked Questions

What does the error code 40411 mean in Kimi Code?

Error code 40411 corresponds to fs.permission_denied, which is the canonical protocol code representing access denial. According to packages/kap-server/src/routes/workspaceFs.ts, this code is returned when OS errors like EACCES or EPERM are mapped through packages/agent-core-v2/src/os/interface/hostFsErrors.ts. It indicates either an OS-level restriction or that the session's current permission mode requires explicit user approval that was not granted.

How do I switch from manual to automatic file access in Kimi Code?

Send the permission.set_mode event to the session with the desired mode set to auto or yolo. Here is the implementation:

await sess.sendEvent('permission.set_mode', { mode: 'auto' });

After sending this event, subsequent file operations will execute without prompting, provided the underlying OS permissions allow access. The mode change is reflected immediately in the session state retrievable via session.getStatus().

Why does Kimi Code deny access to files I can open with my terminal?

This typically occurs when the session runs under a different user context or when the workspace sandbox restricts access outside the configured workDir. Kimi Code does not escalate privileges; it only reports what the OS denies. Check the file ownership and permissions with ls -l or stat, and ensure the server process runs as a user with the necessary rights, or move the file into the session's designated workspace directory.

Where is the permission mode configured by default?

The default permission mode is read from default_permission_mode in your config.toml file. If this value is absent, the system falls back to auto, as verified in packages/node-sdk/test/create-session-transport.test.ts. You can override the default per session by passing explicit configuration or by using the permission.set_mode event after session creation.

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