Global install failed. Try manually: npm install -g @agentme

Error message

Global install failed. Try manually: npm install -g @agentmemory/agentmemory

What it means

When the user accepted the first-run prompt to install agentmemory globally, the CLI ran `npm install -g @agentmemory/agentmemory` via runCommand; if the command returned failure it warns with the manual command instead of persisting the skipGlobalInstall preference. Nothing was installed, so the user must complete installation themselves.

Source

Thrown at src/cli.ts:1236

    p.log.warn(
      "npm not found on PATH. Install manually: npm install -g @agentmemory/agentmemory",
    );
    return;
  }
  const ok = runCommand(
    npmBin,
    ["install", "-g", `@agentmemory/agentmemory@${VERSION}`],
    { label: `Installing @agentmemory/agentmemory@${VERSION} globally` },
  );
  if (ok) {
    p.log.success(
      "Installed globally. `agentmemory stop` etc. will now work in new shells.",
    );
    // Persist so we never re-prompt even if the user happens to npx
    // again from a CI-less TTY.
    writePrefs({ skipGlobalInstall: true });
  } else {
    p.log.warn(
      "Global install failed. Try manually: npm install -g @agentmemory/agentmemory",
    );
  }
}

// iii-console install state.
//   "installed" — `iii-console` is on PATH or at `~/.local/bin/iii-console`
//   "missing"   — binary not found anywhere we look
// We deliberately do NOT probe the console's HTTP port: the binary
// being on disk is the signal we care about (it's not auto-started by
// agentmemory and its default port 3113 collides with our viewer, so
// "is it listening?" is the wrong question at boot time).
type IiiConsoleState =
  | { kind: "installed"; binPath: string }
  | { kind: "missing" };

function detectIiiConsole(): IiiConsoleState {
  const onPath = whichBinary("iii-console");

View on GitHub (pinned to e04ba88819)

Solutions

Re-run manually: `npm install -g @agentmemory/agentmemory` and inspect the real error output.
Fix EACCES by configuring a user-writable prefix (`npm config set prefix ~/.npm-global`) or using a Node version manager instead of sudo.
Verify registry reachability (`npm ping`) and proxy/npmrc settings in restricted networks.
Clear a corrupt cache if install fails on extract: `npm cache clean --force`, then retry.

Example fix

// before: EACCES global install
$ npm install -g @agentmemory/agentmemory  # npm ERR! EACCES
// after: user-writable prefix
$ npm config set prefix ~/.npm-global && export PATH=~/.npm-global/bin:$PATH
$ npm install -g @agentmemory/agentmemory

Defensive patterns

Strategy: retry

Validate before calling

import { execFileSync } from "node:child_process";
// check write access to the global prefix before attempting install
const prefix = execFileSync("npm", ["config", "get", "prefix"], { encoding: "utf8" }).trim();
try { accessSync(prefix, constants.W_OK); } catch {
  console.error("Global prefix not writable; set npm prefix to a user dir first.");
}

Try / catch

const ok = runCommand(npmBin, ["install", "-g", "@agentmemory/agentmemory"]);
if (!ok) {
  console.error("Auto-install failed; run `npm install -g @agentmemory/agentmemory` manually and retry.");
}

Prevention

Use a Node version manager to avoid sudo-required global prefixes.
Verify registry reachability (`npm ping`) behind corporate proxies.
Keep ~50MB free disk for global installs.
Prefer installing the package yourself before first run to skip the prompt entirely.

When it happens

Trigger: Global install prompt accepted → runCommand(npmBin, ["install","-g","@agentmemory/agentmemory"]) exits non-zero: EACCES on the global node_modules prefix, network failure reaching the registry, npm registry auth/proxy issues, or a shim script intercepting npm.

Common situations: System-managed Node (apt/homebrew) requiring sudo for global installs; corporate proxy or offline CI blocking registry.npmjs.org; npm cache corruption; Node version managers switching prefixes mid-install.

Related errors

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/cc932d03bf4d5395. Report an issue: GitHub.