vercel/turborepo · error · ConvertError

invalid_directory

invalid_directory

Error message

Could not find directory at ${workspaceRoot}. Ensure the directory exists.

What it means

getWorkspaceDetails() is the entry point of @turbo/workspaces: it resolves the given root via directoryInfo() and throws ConvertError type invalid_directory if the path does not exist, before any package manager detection runs. The message shows the resolved absolute path.

Source

Thrown at packages/turbo-workspaces/src/get-workspace-details.ts:15

import { ConvertError } from "./errors";
import { MANAGERS } from "./managers";
import { directoryInfo } from "./utils";
import type { Project } from "./types";

export async function getWorkspaceDetails({
  root
}: {
  root: string;
}): Promise<Project> {
  const { exists, absolute: workspaceRoot } = directoryInfo({
    directory: root
  });
  if (!exists) {
    throw new ConvertError(
      `Could not find directory at ${workspaceRoot}. Ensure the directory exists.`,
      {
        type: "invalid_directory"
      }
    );
  }

  for (const { detect, read } of Object.values(MANAGERS)) {
    // eslint-disable-next-line no-await-in-loop -- we want to run serially and bail on the first success
    if (await detect({ workspaceRoot })) {
      return read({ workspaceRoot });
    }
  }

  throw new ConvertError(
    "Could not determine package manager. Add `devEngines.packageManager` or legacy `packageManager` to `package.json`, or ensure a lockfile is present.",
    {
      type: "package_manager-unable_to_detect"

View on GitHub (pinned to 9f94a7d215)

Solutions

Create the directory first: fs.mkdirSync(root, { recursive: true })
Verify the absolute path exists before calling (fs.existsSync(path.resolve(root)))
Fix the typo or flag value that produced the wrong path

Example fix

// before
const project = await getWorkspaceDetails({ root }); // root not created yet

// after
fs.mkdirSync(root, { recursive: true });
const project = await getWorkspaceDetails({ root });

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync, mkdirSync } from "node:fs";
import path from "node:path";

const absRoot = path.resolve(root);
if (!existsSync(absRoot)) mkdirSync(absRoot, { recursive: true });
const project = await getWorkspaceDetails({ root: absRoot });

Type guard

function isInvalidDirectoryError(e: unknown): boolean {
  return e instanceof ConvertError && e.type === "invalid_directory";
}

Try / catch

try {
  await getWorkspaceDetails({ root });
} catch (e) {
  if (e instanceof ConvertError && e.type === "invalid_directory") {
    // message contains the resolved path; re-prompt or create the directory and retry
  } else throw e;
}

Prevention

Always path.resolve() user-supplied roots before workspace APIs
Create target directories with recursive mkdir before reading workspace details
Validate CLI path flags early with a clear usage error

When it happens

Trigger: Calling getWorkspaceDetails({ root }) with a nonexistent directory (relative roots are resolved against the process cwd first), or calling it before the target directory has been created.

Common situations: Scaffolding tools computing a target directory before mkdir; typos in a --path flag; race conditions where the caller creates the directory after the read.

Related errors

AI-assisted analysis of vercel/turborepo@9f94a7d215 (2026-08-16). Data as JSON: /api/errors/afd01e747ef630b0. Report an issue: GitHub.