Troubleshooting Common Issues

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• configuration/installation_instructions.md
• src/container_use_mcp.rs
• extension.toml
• Cargo.toml

This guide provides technical resolutions for common issues encountered when integrating the Container Use Model Context Protocol (MCP) server within the Zed editor. It focuses on binary path resolution, configuration errors, and environment setup for coding agents.

The extension functions by bridging Zed with the cu binary, which provides containerized execution environments. Most issues arise from the extension's inability to locate or execute this binary or missing agent-specific instructions.
Sources: README.md:1-5, extension.toml:1-5

Binary Resolution Issues

The most common failure point is the extension's inability to find the cu binary. The extension follows a specific resolution order: first checking custom settings, then searching the system PATH.

Custom Binary Path Failures

If a cu_path is provided in the Zed settings.json, the extension validates its existence using file metadata. If the path is incorrect or the file is missing, it falls back to a system search.
Sources: src/container_use_mcp.rs:30-35, README.md:16-25

PATH Discovery Failures

The extension attempts to find the binary by executing the which cu command. This requires the process:exec capability.
Sources: extension.toml:10-13, src/container_use_mcp.rs:38-42

The following flowchart illustrates the binary resolution logic:

The extension logic prioritizes cached or configured paths before falling back to shell-based discovery.
Sources: src/container_use_mcp.rs:27-55

Configuration Errors

Issues may arise from malformed JSON in Zed's settings.json or incorrect parameter types. The extension uses a structured settings object for deserialization.

Setting	Type	Description	Source
cu_path	Option<String>	Explicit path to the cu executable.	src/container_use_mcp.rs:13-16

Invalid Settings Schema

The extension generates a JSON schema for settings validation. If the settings.json does not match the ContainerUseMcpSettings struct, the extension may fail to apply custom paths and default to PATH-based discovery.
Sources: src/container_use_mcp.rs:12-16, src/container_use_mcp.rs:88-91

Command Initialization Flow

The sequence below shows how settings are loaded during the initialization of the context server command.

Agent Rule Misconfigurations

Coding agents within Zed require specific instructions to utilize the containerized environment provided by the MCP server. Without these rules, agents may attempt to execute commands in the local host environment instead of the container.

Missing .rules File

A .rules file must exist in the project root to direct agents toward the containerized environment.
Sources: configuration/installation_instructions.md:1-1, README.md:27-33

Resolution:
Download the recommended agent rules using the following command in the project root:

curl -o .rules https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md

Sources: README.md:31-33

Environment and Dependency Issues

The extension is built as a cdylib and depends on the zed_extension_api. Ensure the following requirements are met:

• Zed Version: Requires an editor version compatible with zed_extension_api v0.5.0.
• Binary Installation: The cu binary must be built from source if not available via a package manager.
• Capabilities: The extension must have permission to execute which to locate dependencies.
  Sources: Cargo.toml:11-16, extension.toml:10-13, README.md:7-11

Summary of Resolution Steps

Issue	Likely Cause	Solution
Failed to find cu	Binary not in PATH	Install cu or set cu_path in settings.
Agent ignores container	Missing .rules	Add agent.md rules to project root as .rules.
Extension won't start	API Incompatibility	Update Zed or check Cargo.toml for zed_extension_api version.
Custom path ignored	File missing/invalid	Verify file permissions and path accuracy in settings.json.
Sources: README.md:16-33, src/container_use_mcp.rs:52-54, Cargo.toml:16-16

This troubleshooting guide ensures that the link between Zed's MCP client and the cu binary is robust by verifying paths, configuration schemas, and agent-level instructions.