Troubleshooting Common Cline Errors: ASDF/Node.js and Shell Integration Issues

date

Apr 17, 2025

slug

troubleshooting-cline-errors

status

Published

Issue 1: Resolving "No version is set for command npx" with ASDF and MCP

Symptom:

When using Node.js installed via asdf and configuring Cline's Model Context Protocol (MCP), you might encounter an error similar to this when trying to use commands like npx:


No version is set for command npx
Consider adding one of the following versions in your config file at //path/to/.tool-versions
MCP error -32000: Connection closed

Cause:

The Cline MCP environment doesn't automatically inherit all the necessary environment variables set up by asdf to manage Node.js versions and locate executables correctly. It needs to be explicitly told where to find the asdf shims and which version of Node.js to use.

Solution:

You need to add specific environment variables to the env section within your mcp settings JSON configuration file. This ensures the MCP process has the correct context.

Modify your MCP settings JSON file to include an env block like this:


{
  "mcpServers": {
    "some-mcp-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "disabled": false,
      "autoApprove": [],
      "env": {
        "PATH": "/path/to/your/home/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/path/to/asdf/install/libexec",
        "ASDF_DATA_DIR": "/path/to/your/home/.asdf",
        "ASDF_NODEJS_VERSION": "YOUR_NODE_VERSION"
      }
    }
  }
}

Explanation:

PATH: Crucially includes the path to your asdf shims directory (~/.asdf/shims by default) before standard system paths like /usr/bin. This ensures asdfmanaged commands are found first. Adjust the rest of the PATH (:/usr/bin:/bin) if your system default is different.

ASDF_DIR: Points to the core asdf installation directory. This might be under /opt/homebrew/opt/asdf/libexec if installed via Homebrew on macOS, or ~/.asdf if installed manually.

ASDF_DATA_DIR: Points to the asdf data directory where plugins and installed versions reside (typically ~/.asdf).

ASDF_NODEJS_VERSION: Explicitly tells asdf which version of Node.js to activate within the MCP environment. Replace "YOUR_NODE_VERSION" with the actual version string specified in your .tool-versions file (e.g., "20.13.1").

Reference: GitHub Issue Comment on cline/cline#1125

Issue 2: Fixing Hung Commands (Shell Integration Unavailable)

Symptom:

When you execute a command via Cline, the command runs, but Cline seems to hang or doesn't register that the command has finished, preventing further interaction or expected follow-up actions. This often manifests as a "Shell Integration Unavailable" warning or simply non-responsive behavior.

Cause:

This frequently occurs when Cline cannot properly integrate with your shell, especially within integrated terminals like the one in Visual Studio Code. The necessary hooks or scripts that allow Cline to monitor command execution status aren't being loaded correctly.

Solution:

If you are using zsh as your shell, particularly within the VS Code integrated terminal, you can often resolve this by ensuring the VS Code shell integration scripts are loaded correctly.

Add the following line to your ~/.zshrc configuration file:


[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)"

Explanation:

[[ "$TERM_PROGRAM" == "vscode" ]]: This checks if the current terminal environment variable TERM_PROGRAM is set to vscode. This ensures the integration script is only sourced when running inside VS Code's terminal.

&&: If the check is true (you are in VS Code's terminal)...

. "$(code --locate-shell-integration-path zsh)": This executes the code --locate-shell-integration-path zsh command, which outputs the path to the VS Code shell integration script for zsh. The . (source) command then loads this script into your current shell session.

After adding this line, restart your terminal or source your ~/.zshrc file (e.g., by running source ~/.zshrc) for the changes to take effect.

Reference: Cline Wiki - Troubleshooting Shell Integration

By correctly configuring the environment for MCP processes and ensuring proper shell integration, you can resolve these common Cline issues and enjoy a smoother workflow. Always refer to the official Cline documentation and GitHub repository for further troubleshooting assistance.

Troubleshooting Common Cline Errors: ASDF/Node.js and Shell Integration Issues

Issue 1: Resolving "No version is set for command npx" with ASDF and MCP

Issue 2: Fixing Hung Commands (Shell Integration Unavailable)

Tags

Previous Article