Failed to copy studio assets from "${studioSource}" to "${st

Error message

Failed to copy studio assets from "${studioSource}" to "${studioServePath}": ${err instanceof Error ? err.message : err}

What it means

The sandbox deployer's prepare step copies the bundled Studio UI assets from the package's dist/studio directory into the deploy output directory. If the recursive copy (fs copy with overwrite) fails for any reason, it is wrapped in this error preserving the original message and both paths.

Source

Thrown at deployers/sandbox/src/deployer.ts:124

      mastra.__registerInternalWorkflow(scoreTracesWorkflow);
    }
    `;
  }

  async prepare(outputDirectory: string): Promise<void> {
    await super.prepare(outputDirectory);

    if (this.studio) {
      const __filename = fileURLToPath(import.meta.url);
      const __dirname = dirname(__filename);

      const studioSource = join(dirname(__dirname), 'dist', 'studio');
      const studioServePath = join(outputDirectory, this.outputDir, 'studio');

      try {
        await copy(studioSource, studioServePath, { overwrite: true });
      } catch (err) {
        throw new Error(
          `Failed to copy studio assets from "${studioSource}" to "${studioServePath}": ${err instanceof Error ? err.message : err}`,
        );
      }
    }
  }

  async bundle(
    entryFile: string,
    outputDirectory: string,
    { toolsPaths, projectRoot }: { toolsPaths: (string | string[])[]; projectRoot: string },
  ): Promise<void> {
    return this._bundle(this.getEntry(), entryFile, { outputDirectory, projectRoot }, toolsPaths);
  }

  /**
   * Deploy the built output into the sandbox and wait for the server to come
   * up on its public URL. Writes `sandbox-deployment.json` into the output
   * directory and updates the Edge Config alias when configured.

View on GitHub (pinned to 75dd419e61)

Solutions

Read the wrapped inner message for the underlying fs error
Verify node_modules/@mastra/deployers-sandbox/dist/studio exists (reinstall if missing)
Check write permissions and disk space on outputDirectory
Avoid bundlers/minifiers that prune package dist assets for this deployer

Example fix

// before (bundler externals pruning assets)
// after: mark package as external / install via package manager
pnpm install --force @mastra/deployers-sandbox
chmod -R u+w ./output

Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync } from 'node:fs';
const studioSource = join(dirname(require.resolve('@mastra/deployers-sandbox')), 'dist', 'studio');
if (!existsSync(studioSource)) throw new Error('package install is missing dist/studio — reinstall');
if (process.getuid && !accessOk(outputDirectory)) await fs.mkdir(outputDirectory, { recursive: true });

Try / catch

try {
  await deployer.prepare(outputDirectory);
} catch (err) {
  if (String(err).startsWith('Failed to copy studio assets')) {
    console.error('check dist/studio exists and outputDirectory is writable:', err.message);
  } else throw err;
}

Prevention

Reinstall the package if dist/studio is missing
Verify write permissions and free disk space on outputDirectory in CI
Avoid bundling steps that strip package dist assets

When it happens

Trigger: prepare() runs and copy(studioSource, studioServePath) throws — e.g. the source dist/studio doesn't exist, the output directory is not writable, disk is full, or a filesystem error (EPERM/ENOENT/ENOSPC) occurs.

Common situations: Installing @mastra/deployers-sandbox with a bundler that strips non-JS assets so dist/studio is missing; read-only CI filesystem or missing write permissions on outputDirectory; partial installs with corrupted package contents.

Related errors

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