Fixing "asdf error no plugin named completion" in zsh

When working with the asdf version manager in zsh, you may encounter an error when sourcing your .zshrc file:

Unknown command: `asdf completion zsh`
No plugin named completion

This error typically occurs due to a version mismatch between asdf and oh-my-zsh, often after recent updates to either tool.

Problem Overview

The error indicates that oh-my-zsh's asdf plugin is trying to execute asdf completion zsh, but your installed version of asdf doesn't support this command structure. This usually happens when:

• You've recently updated oh-my-zsh
• Your asdf installation is outdated
• There's a breaking change between asdf versions

Solution: Upgrade asdf

The most effective solution is to upgrade your asdf installation to version 0.16.0 or later, which includes the completion command that oh-my-zsh expects.

Method 1: Using Package Manager (Recommended)

If you installed asdf via a package manager like Homebrew:

# For Homebrew users
brew upgrade asdf

# For Linux package managers, use appropriate command
# sudo apt update && sudo apt upgrade asdf  # Example for Debian/Ubuntu

Method 2: Manual Upgrade

If you installed asdf manually or need a specific version:

1. Download the latest release from the asdf GitHub releases page

2. Replace your current asdf installation with the new version

3. Update your .zshrc with the correct paths:

export ASDF_DATA_DIR="$HOME/.asdf"
export PATH="$ASDF_DATA_DIR/shims:$PATH"

4. Regenerate shims:

asdf reshim

WARNING

If upgrading from asdf v0.15.x or earlier, follow the official migration guide as there are breaking changes.

Method 3: Alternative oh-my-zsh Configuration

If you cannot upgrade asdf immediately, you can modify your oh-my-zsh configuration to avoid the problematic completion command:

# Instead of using the asdf plugin, source asdf directly
plugins=(${plugins:#asdf})  # Remove asdf from plugins array
source "$HOME/.asdf/asdf.sh"  # Source asdf directly

Verification

After applying the fix, verify your setup:

# Source your updated zshrc
source ~/.zshrc

# Check asdf version
asdf --version

# Test that completion works
asdf completion zsh

Prevention

To avoid similar issues in the future:

• Keep both oh-my-zsh and asdf updated regularly
• Check for breaking changes in release notes before major updates
• Consider using version pinning for critical development tools

TIP

If you continue experiencing issues after upgrading, check the asdf GitHub issues for similar problems and solutions.

The version incompatibility between oh-my-zsh and older asdf versions causes this error, and upgrading asdf is the recommended solution that maintains full functionality of both tools.