nocobase/nocobase · error · Error

Couldn't find a NocoBase source project from --cwd: ${fallba

Error message

Couldn't find a NocoBase source project from --cwd: ${fallback}

What it means

After the existence/directory checks, resolveProjectCwd walks up parent directories looking for a local NocoBase binary (node_modules/.bin/nocobase-v1). If the filesystem root is reached without finding one AND --cwd was explicitly provided, this error is thrown. It means the given directory is not inside a NocoBase source project with installed dependencies.

Source

Thrown at packages/core/cli/src/lib/run-npm.ts:174

}

export function resolveProjectCwd(cwd?: string): string {
  const normalizedCwd = typeof cwd === 'string' && cwd.trim() === '' ? undefined : cwd;
  const fallback = resolveCwd(normalizedCwd);
  const hasExplicitInput = normalizedCwd !== undefined;
  if (hasExplicitInput && !pathExists(fallback)) {
    throw new Error(`The specified --cwd does not exist: ${fallback}`);
  }
  if (hasExplicitInput && !isDirectory(fallback)) {
    throw new Error(`The specified --cwd is not a directory: ${fallback}`);
  }
  let current = hasExplicitInput ? fallback : process.cwd();

  while (!hasLocalNocoBaseBinary(current)) {
    const parent = path.dirname(current);
    if (parent === current) {
      if (hasExplicitInput) {
        throw new Error(`Couldn't find a NocoBase source project from --cwd: ${fallback}`);
      }
      return fallback;
    }
    current = parent;
  }

  return current;
}

export async function run(name: string, args: string[], options?: RunProcessOptions): Promise<void> {
  const cwd = resolveCwd(options?.cwd);
  const label = options?.errorName ?? name;
  const command = await resolveCommandName(name);
  const stdio: StdioOptions = shouldTeeInheritedOutput(options)
    ? ['inherit', 'pipe', 'pipe']
    : (options?.stdio ?? 'inherit');
  return await new Promise((resolve, reject) => {
    const child = spawn(command, [...args], {

View on GitHub (pinned to fa42722fef)

Solutions

  1. Run `yarn install` (or npm install) in the target project so node_modules/.bin/nocobase-v1 exists.
  2. Point --cwd at the actual NocoBase source root (the repo containing packages/ and node_modules).
  3. Verify the marker file exists: ls <project>/node_modules/.bin/nocobase-v1.
  4. If you are not in a source project, run the command from a location where the default (process.cwd) fallback is acceptable.

Example fix

# before
cd ~/empty-dir && nocobase dev --cwd ~/empty-dir   # Error: Couldn't find a NocoBase source project
# after
cd ~/nocobase && yarn install && nocobase dev --cwd ~/nocobase
Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs';
function hasNocoBaseBinary(dir: string): boolean {
  return fs.existsSync(path.join(dir, 'node_modules', '.bin', 'nocobase-v1'));
}
if (!hasNocoBaseBinary(projectDir) && !walkUpHas(projectDir)) {
  throw new Error(`Run yarn install in the NocoBase project; no nocobase-v1 binary found from ${projectDir}`);
}

Try / catch

try {
  await nocobaseCommand({ cwd: projectDir });
} catch (err) {
  if (err instanceof Error && err.message.includes("Couldn't find a NocoBase source project")) {
    console.error('Install dependencies (yarn install) in a NocoBase source checkout, or point --cwd at it.');
  } else throw err;
}

Prevention

When it happens

Trigger: `nocobase <cmd> --cwd ~/some-random-dir` where no ancestor contains node_modules/.bin/nocobase-v1 — e.g. dependencies not installed (no yarn install), a non-NocoBase project, or a project whose nocobase-v1 binary name differs.

Common situations: Freshly cloned repo where `yarn install` was never run; running from an empty scratch directory; NocoBase installed globally rather than as a local source dependency; renamed node_modules via workspaces misconfiguration.

Related errors

AI-assisted analysis of nocobase/nocobase@fa42722fef (2026-09-01). Data as JSON: /api/errors/c1157db3b4b283d4. Report an issue: GitHub.