What causes "Unsupported artifact file type: ${artifactPath}" in mastra-ai/mastra?

Delete the special file listed in the message (e.g. `rm mypipe` / remove the .sock file) and rebuild.

Unsupported artifact file type: ${artifactPath}

Error message

Unsupported artifact file type: ${artifactPath}

What it means

The artifact collector only understands regular files, directories, and symbolic links (per lstat). Any other filesystem entry — FIFOs, sockets, device files — found in the bundler output directory cannot be represented in the artifact manifest, so the build throws with the entry's path. This guards manifest integrity: the digest list must fully describe the artifact.

Source

Thrown at packages/cli/src/commands/experiment/ExperimentBundler.ts:286

        });
      } else if (stats.isSymbolicLink()) {
        const target = await readlink(fullPath);
        if (isAbsolute(target)) {
          throw new Error(`Experiment worker artifacts cannot contain absolute symlinks: ${artifactPath}`);
        }
        const resolvedTarget = resolve(dirname(fullPath), target);
        const artifactTarget = relative(root, resolvedTarget);
        if (artifactTarget === '..' || artifactTarget.startsWith(`..${sep}`) || isAbsolute(artifactTarget)) {
          throw new Error(`Experiment worker artifacts cannot contain escaping symlinks: ${artifactPath}`);
        }
        files.push({
          path: artifactPath,
          type: 'symlink',
          target,
          sha256: createHash('sha256').update(target).digest('hex'),
        });
      } else {
        throw new Error(`Unsupported artifact file type: ${artifactPath}`);
      }
    }
  };
  await visit(root);
  return files;
}

View on GitHub (pinned to 75dd419e61)

Solutions

Delete the special file listed in the message (e.g. `rm mypipe` / remove the .sock file) and rebuild.
Find what creates it (a dev server, watcher, or script) and redirect it to /tmp or another directory.
Ensure outputDir points to a dedicated build directory (default .mastra/experiment-worker) that nothing else writes runtime files into.
Clean the output directory fully before rebuilding.

Example fix

// before
# output dir contains a fifo created by a local dev server
$ rm .mastra/experiment-worker/myfifo
// after
# configure the dev server socket path outside the output dir, e.g. /tmp/app.sock, then rebuild

Defensive patterns

Strategy: validation

Validate before calling

import { lstat, readdir } from 'node:fs/promises';
import { join } from 'node:path';
async function assertOnlyRegularFiles(dir: string) {
  for (const e of await readdir(dir, { withFileTypes: true })) {
    const p = join(dir, e.name);
    if (e.isDirectory()) await assertOnlyRegularFiles(p);
    else {
      const st = await lstat(p);
      if (!st.isFile() && !st.isSymbolicLink()) throw new Error(`special file in build output: ${p}`);
    }
  }
}

Type guard

null

Try / catch

try {
  await buildExperimentWorker({ outputDir });
} catch (e) {
  if (String(e?.message).includes('Unsupported artifact file type')) {
    console.error('Remove the FIFO/socket/device file listed and redirect whatever creates it');
  } else throw e;
}

Prevention

Point dev-server sockets/pipes outside the build output directory
Use a dedicated output directory nothing else writes into
Clean the output dir before builds
Find and fix crashed processes leaving IPC files behind

When it happens

Trigger: collectFileDigests walks the output directory and lstat() returns a type that is neither file, directory, nor symlink (e.g. a named pipe or socket created in the output dir).

Common situations: A dev server or tool that creates a Unix socket/FIFO inside the project or output directory; a previous crashed process leaving a pipe in the build dir; misconfigured outputDir pointing at a directory containing runtime IPC files.

Related errors

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