ruvnet/ruflo · error · Error

${result.stderr?.toString() || 'Installation failed'}

Error message

${result.stderr?.toString() || 'Installation failed'}

What it means

Produced by ensurePackageInstalled() in auto-install.ts:73 when `spawnSync('npm', ['install', pkg, ...])` exits non-zero. The thrown message is npm's stderr (or 'Installation failed' when stderr is empty). The function then catches this error, logs '[claude-flow] Failed to auto-install <pkg>: <error>' unless silent, and returns false — so callers usually see a degraded/missing-package result rather than the throw itself.

Source

Thrown at v3/@claude-flow/cli/src/mcp-tools/auto-install.ts:73

    return false;
  }
  installAttempts.add(packageName);

  try {
    if (!silent) {
      console.error(`[claude-flow] Auto-installing ${packageName}...`);
    }

    // Use spawn with array args to prevent shell injection
    const args = ['install', packageName, save ? '--save' : '--no-save'];
    const result = spawnSync('npm', args, {
      stdio: silent ? 'pipe' : ['pipe', 'pipe', 'pipe'],
      timeout,
      shell: false, // Explicitly disable shell
    });

    if (result.status !== 0) {
      throw new Error(result.stderr?.toString() || 'Installation failed');
    }

    if (!silent) {
      console.error(`[claude-flow] Successfully installed ${packageName}`);
    }
    return true;
  } catch (error) {
    if (!silent) {
      console.error(`[claude-flow] Failed to auto-install ${packageName}: ${error}`);
    }
    return false;
  }
}

/**
 * Try to import a package, auto-install if not found, and retry
 *
 * @param packageName - npm package name

View on GitHub (pinned to fa13ee4ad6)

Solutions

  1. Run `npm install <package>` manually in the project root — npm's full diagnostic output shows the real cause (404 vs auth vs network)
  2. Fix environment: add registry/token to .npmrc, set HTTP(S)_PROXY, or run `npm cache clean --force` for cache corruption
  3. Pre-install optional dependencies in your image/Dockerfile so the auto-install path never runs
  4. Pin an existing version if the failure is E404 on a tag that does not exist

Example fix

# before: relying on runtime auto-install in CI
# (auto-install fails offline -> tool degrades)

# after: pre-install in the image
RUN npm install --save <optional-package>
# app then resolves it locally; auto-install is skipped
Defensive patterns

Strategy: fallback

Validate before calling

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
function resolvesLocally(pkg: string): boolean {
  try { require.resolve(pkg); return true; } catch { return false; }
}
// pre-install path: if not resolvable, preinstall instead of relying on auto-install
if (!resolvesLocally(pkg) && !canReachRegistry()) {
  console.error('pre-installing optional deps');
  await exec('npm install');
}

Try / catch

// auto-install already swallows the throw and returns false; handle that contract:
const ok = await ensurePackageInstalled(pkg);
if (!ok) {
  // fall back: degrade the feature, or surface manual install instructions
  return { degraded: true, hint: `npm install ${pkg} manually to enable this feature` };
}

Prevention

When it happens

Trigger: Any npm install failure inside the auto-install path: package or version not found (E404), registry unreachable (ENOTFOUND, EAI_AGAIN, ETIMEDOUT), private scoped package without credentials (E401/E403), corporate proxy or air-gapped network blocking registry.npmjs.org, corrupted npm cache, or the spawnSync timeout elapsing.

Common situations: CI runners without network egress; private @scope packages needing an .npmrc token; a typo'd optional dependency name; Node/npm version mismatch; environments where 'npm' is not on PATH for the MCP server process (ENOENT surfaces as 'Installation failed').

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/20c0ee72590295b8. Report an issue: GitHub.