`cd: function definition file not found` in agent shell (zsh) breaks any command using cd

Bug Reports
1

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

Environment

  • macOS: darwin 25.1.0
  • Shell: zsh
  • Cursor: using AI agents + git worktrees (but repro is not specific to worktrees)
  • Agent commands are executed via something like zsh -lc '…' inside a sandbox

Summary

When Cursor’s AI agent runs shell commands that include cd, they often fail with:

(eval):1: cd: function definition file not found

This happens even for simple, valid commands such as:

cd /some/dir && pnpm lint

The root cause appears to be how Cursor configures zsh inside the sandbox: cd is turned into an autoload stub function without a backing definition in $FPATH, so any cd call fails.

Steps to reproduce

In a Cursor AI agent task (or via the internal sandbox terminal), run:

cd / && pwd

or from a tool-like context (what I see in logs):

cd /Users/<user>/.cursor/worktrees/<repo>/<worktree>/functions && pnpm lint

Observed in sandbox:

  1. Inspect cd:
functions cd 2>/dev/null | sed -n '1,5p'
type cd

Output:

cd () {
    # traced
    builtin autoload -XUz
}

cd is a shell function from zsh
cd is a shell builtin
cd is /usr/bin/cd
  1. Try to use cd:
cd / && pwd

Output:

(eval):1: cd: function definition file not found
  1. But explicitly calling the builtin works:
builtin cd / && pwd
# → /   (works correctly)

In a normal terminal on the same machine (outside Cursor), cd is just a builtin and works fine.

Expected behavior

  • cd should work normally in the agent shell (as a builtin or a valid function wrapper), so commands like:

    cd <path> && pnpm lint

    do not fail with function definition file not found.

Actual behavior

  • Inside Cursor’s sandbox shell:

    • cd is a function stub:

      cd () {
    # traced
    builtin autoload -XUz
}

    • There is no corresponding function file for cd in $FPATH (e.g. no /usr/share/zsh/5.9/functions/cd*), so autoload -XUz fails and every cd invocation produces:

      cd: function definition file not found

    • Workaround builtin cd <dir> works, but standard cd does not.

Notes / Analysis

  • My personal zsh config (~/.zshenv, ~/.zprofile, /etc/zsh*, ~/.oh-my-zsh, etc.) does not define cd or autoload it. In a clean zsh -lc outside Cursor, type cd shows only the builtin and no functions[cd] entry.

  • The autoload stub:

    cd () {
    # traced
    builtin autoload -XUz
}

    is typical of functions -t cd (zsh tracing) or similar, so it looks like Cursor’s own sandbox setup is enabling function tracing for cd, but there is no actual cd function file in $FPATH.

  • Because this setup happens after user dotfiles (~/.zshenv) are processed, I cannot reliably override/fix cd from my config for the agent shell.

Suggested fixes

Any of these would resolve the issue:

  1. Don’t trace cd (avoid turning it into an autoload stub), or

  2. Provide a real cd function file in $FPATH if you want to trace it, or

  3. After enabling tracing, explicitly restore cd to a safe wrapper, e.g.:

    cd() { builtin cd "$@"; }

Until it’s fixed, a reliable workaround on the agent side is to always use builtin cd in commands, e.g.:

builtin cd /Users/<user>/.cursor/worktrees/<repo>/<worktree>/functions && pnpm lint

—but it would be much better if cd just worked normally inside the Cursor agent shell.

Steps to Reproduce

described in Describe the Bug section

Expected Behavior

described in Describe the Bug section

Operating System

MacOS

Current Cursor Version (Menu → About Cursor → Copy)

Version: 2.1.19
VSCode Version: 1.105.1
Commit: 39a966b4048ef6b8024b27d4812a50d88de29cc0
Date: 2025-11-21T22:59:02.376Z (14 hrs ago)
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 25.1.0

For AI issues: which model did you use?

gpt 5.1, sonnet and maybe others

For AI issues: add Request ID with privacy disabled

Request ID: f96ad866-18cf-4338-8668-a5a416927388

Does this stop you from using Cursor

No - Cursor works, but with this issue

2

Hey, thanks for the report. You’ve done a great job analyzing the problem and almost pinpointing the root cause.

This looks like a new issue related to how the agent sandbox applies function tracing to cd without providing the function definition file. I don’t see similar reports in the forum, so this is really helpful information.

I’ll pass this on to the engineering team along with your suggested fixes:

  • Don’t apply tracing to cd, or
  • Provide a real cd function file in $FPATH, or
  • Restore cd to a safe wrapper after tracing

Your workaround of using builtin cd in commands looks like a good temporary solution for now.

Could you also try the “Legacy Terminal Tool” setting as a possible workaround?

  • Open Cursor Settings with Cmd+Shift+J
  • Go to Agents → Inline Editing & Terminal
  • Enable “Legacy Terminal Tool”
  • Press Cmd+Shift+P → “Terminal: Kill All Terminals”
  • Fully restart Cursor

Please let me know if this helps or if the issue still happens in legacy mode.

3

Hello! I’ve tried legacy terminal tool, but the problem still there:(
cd: function definition file not found

4

Thanks for confirming. Unfortunately, the issue is deeper than the Legacy Terminal Tool - it’s a bug in how sandbox-exec instruments zsh builtins.

Engineering is already working on a fix. Temporary options for now:

  1. Disable the sandbox: Settings → Cursor Settings → Agents → Auto-Run → select “Ask Every Time,” then click Run or Add to allowlist
  2. Use the builtin cd in commands (as you’ve already found)

This is a priority since it breaks core functionality for zsh users.