Skip to content

docs: Add troubleshooting for Linux EXDEV cross-device link error during Claude Code plugin install #109

@alaslibress

Description

@alaslibress

📋 Pre-flight Checks

  • I searched existing issues and this is not a duplicate
  • I have a link to the specific doc page or section that needs improvement

📄 Which Document?

docs/AGENT-SETUP.md

🔍 What's Wrong or Missing?

Following the recent update that fixed the marketplace.json schema, Linux users can finally proceed with the Claude Code plugin installation. However, users on distributions where /home and /tmp are mounted on different filesystems (which is the default partitioning on Fedora, openSUSE, Arch Linux, and many Ubuntu Server setups) will immediately hit a hard crash:

EXDEV: cross-device link not permitted, rename '/home/user/.claude/plugins/cache/engram' -> '/tmp/claude-plugin-temp-...'

This happens because Claude Code's plugin installer (running on Node.js) attempts to use fs.rename() to move the downloaded plugin across partition boundaries, which Node.js natively rejects. This completely blocks the installation for these users. There is currently no mention of this upstream limitation or its workaround in our documentation.

💡 Suggested Improvement

Troubleshooting: Claude Code plugin installation on Linux

EXDEV: cross-device link not permitted during plugin install

On Linux systems where /home and /tmp are on different partitions or filesystems, Claude Code's plugin installer fails because Node.js fs.rename() cannot move files across filesystem boundaries.

Workaround — redirect the temp directory to the same filesystem as ~/.claude:

mkdir -p ~/.cache/claude-tmp
TMPDIR=~/.cache/claude-tmp claude plugin marketplace add Gentleman-Programming/engram
TMPDIR=~/.cache/claude-tmp claude plugin install engram

Or make it permanent in your shell profile (~/.bashrc, ~/.zshrc):

export TMPDIR="$HOME/.cache/claude-tmp"

This is a known Claude Code issue ([#14799](anthropics/claude-code#14799)) affecting all plugin installations on Linux with separate /tmp, not specific to Engram.

Docker users: This does not affect Docker containers since the entire filesystem is typically a single overlay mount.

📎 Additional Context

This is a documented limitation in the Claude Code CLI itself, independent of Engram, but Engram users will be the ones experiencing it directly now that the marketplace schema is unblocked. 

- Upstream Anthropic issue: https://github.com/anthropics/claude-code/issues/14799
- I have personally verified the issue and tested the `TMPDIR` workaround successfully on Fedora Linux natively. 
- Once this issue receives the `status:approved` label, I have the PR ready to submit.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions