copyFile ${src} -> ${dest} failed (exit ${result.exitCode}):

Error message

copyFile ${src} -> ${dest} failed (exit ${result.exitCode}): ${result.stderr.trim()}

What it means

This generic Error comes from SandboxFilesystem.copyFile in its atomic/structured branch: a multi-line shell probe ran and exited with a code that is neither EXIT_NOT_FOUND nor EXIT_EXISTS. The library reserves those two codes for FileNotFoundError and FileExistsError; anything else (permission denied, cross-device copy failure, cp syntax/behavior issues, sandbox instability) is rethrown with the raw exit code and stderr. The probe script typically checks existence/overlap before invoking cp, so this indicates the cp step or an intermediate check failed unexpectedly.

Source

Thrown at mastracode/sdk/src/agents/sandbox-filesystem.ts:349

          `src=${shellQuote(srcAbs)}`,
          `dest=${shellQuote(destAbs)}`,
          `if [ ! -e "$src" ] && [ ! -L "$src" ]; then exit ${EXIT_NOT_FOUND}; fi`,
          `mkdir -p ${shellQuote(posixPath.dirname(destAbs))} || exit 1`,
          `if [ -d "$src" ]; then`,
          `  mkdir "$dest" 2>/dev/null || exit ${EXIT_EXISTS}`,
          `  cp -R "$src"/. "$dest"/`,
          `else`,
          `  tmp="$dest.__cptmp$$"`,
          `  cp "$src" "$tmp" || exit 1`,
          `  ln "$tmp" "$dest" 2>/dev/null || { rm -f "$tmp"; [ -e "$dest" ] && exit ${EXIT_EXISTS} || exit 1; }`,
          `  rm -f "$tmp"`,
          `fi`,
        ].join('\n'),
      );
      if (result.exitCode === EXIT_NOT_FOUND) throw new FileNotFoundError(src);
      if (result.exitCode === EXIT_EXISTS) throw new FileExistsError(dest);
      if (result.exitCode !== 0) {
        throw new Error(`copyFile ${src} -> ${dest} failed (exit ${result.exitCode}): ${result.stderr.trim()}`);
      }
      return;
    }
    const result = await this.exec(
      `if [ ! -e ${shellQuote(srcAbs)} ]; then exit ${EXIT_NOT_FOUND}; fi; mkdir -p ${shellQuote(posixPath.dirname(destAbs))} && cp ${recursive}${shellQuote(srcAbs)} ${shellQuote(destAbs)}`,
    );
    if (result.exitCode === EXIT_NOT_FOUND) throw new FileNotFoundError(src);
    if (result.exitCode !== 0) {
      throw new Error(`copyFile ${src} -> ${dest} failed (exit ${result.exitCode}): ${result.stderr.trim()}`);
    }
  }

  async moveFile(src: string, dest: string, options?: CopyOptions): Promise<void> {
    const srcAbs = await this.resolveAsync(src);
    const destAbs = await this.resolveAsync(dest);
    await this.assertContainedRealpath(srcAbs, src);
    await this.assertContainedDest(destAbs, dest);
    if (options?.overwrite === false) {

View on GitHub (pinned to 75dd419e61)

Solutions

Inspect the stderr embedded in the message for the exact shell failure.
Verify src is readable and dest's parent directory is writable by the sandbox user.
Ensure dest is not a directory path that would cause cp semantics conflicts; pick an explicit file name for dest.
Retry with simpler options (no noOverwrite/atomic flag) to isolate whether the probe block or plain cp path is failing.
Recreate or restart the sandbox if filesystem state appears corrupted.

Example fix

// before — dest is an existing directory, cp behaves unexpectedly
await sandbox.fs.copyFile('/app/report.pdf', '/out');

// after — explicit destination file path
await sandbox.fs.copyFile('/app/report.pdf', '/out/report.pdf');

Defensive patterns

Strategy: try-catch

Validate before calling

// verify src readable and dest parent usable before copying
await sandbox.fs.stat(src);
const destDir = destPath.dirname(dest);
if (!(await sandbox.fs.isDirectory(destDir))) {
  await sandbox.fs.mkdir(destDir, { recursive: true });
}

Type guard

function isFileExistsError(e: unknown): e is FileExistsError {
  return e instanceof FileExistsError;
}

Try / catch

try {
  await sandbox.fs.copyFile(src, dest, { noOverwrite: true });
} catch (e) {
  if (isFileExistsError(e)) return; // dest already present
  if (e instanceof FileNotFoundError) throw new Error(`src missing: ${src}`);
  throw e; // unexpected shell failure: surface stderr from message
}

Prevention

Use explicit file paths for dest, never bare directory paths.
Pre-create the dest parent directory with mkdir recursive.
Catch the typed FileNotFoundError/FileExistsError separately from the generic failure.
Check sandbox disk space and mount permissions before bulk copies.

When it happens

Trigger: Calling sandbox.files.copyFile(src, dest, options) where the probe-and-copy shell block fails: dest parent cannot be created, cp lacks read permission on src or write permission on dest dir, src and dest resolve oddly (device/overlay boundaries), or the shell itself errors mid-script.

Common situations: Copying into a read-only or full sandbox mount; copying a file the current sandbox user cannot read; a malformed or relative dest that resolves outside an allowed root; sandbox snapshot/restore leaving stale permissions.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/fb44cad4ccabafd1. Report an issue: GitHub.