affaan-m/ECC · error · Error

ECC_MEMORY_HARNESS must identify this MCP server with a…

Error message

ECC_MEMORY_HARNESS must identify this MCP server with a lowercase harness slug.

What it means

The memory MCP server must know which harness (Claude Code, Codex, Cursor, etc.) is connecting, both for scoping and diagnostics. resolveServiceSecurity reads ECC_MEMORY_HARNESS and requires it to be a string matching SLUG_REGEXP (lowercase slug). Otherwise it throws at startup/tool resolution time.

Solutions

Set ECC_MEMORY_HARNESS to a lowercase slug like 'claude-code' in the MCP server env config
If launching programmatically, pass { harness: 'claude-code' } in options instead
Check for typos/whitespace/uppercase in the configured value

Example fix

// before
"env": {}
// after
"env": { "ECC_MEMORY_HARNESS": "claude-code" }

Defensive patterns

Strategy: validation

Validate before calling

const v = process.env.ECC_MEMORY_HARNESS; if (typeof v !== 'string' || !/^[a-z0-9-]+$/.test(v)) throw new Error('ECC_MEMORY_HARNESS must be a lowercase slug like claude-code');

Type guard

const isValidHarnessSlug = (v) => typeof v === 'string' && /^[a-z][a-z0-9-]*$/.test(v);

Try / catch

try { const security = resolveServiceSecurity(); /* ... */ } catch (e) { if (/ECC_MEMORY_HARNESS/.test(e.message)) { console.error('Set ECC_MEMORY_HARNESS (e.g. claude-code) in the MCP server env'); process.exit(1); } throw e; }

Prevention

Set ECC_MEMORY_HARNESS in the mcpServers env block for every harness install
Keep the value lowercase-hyphenated; avoid spaces and uppercase
When launching programmatically, pass options.harness explicitly instead of relying on env

When it happens

Trigger: resolveServiceSecurity() is called with neither options.harness nor a valid env.ECC_MEMORY_HARNESS — the variable is unset, empty, contains uppercase/invalid characters, or fails the slug regex.

Common situations: Running the MCP server directly without the harness wrapper that sets ECC_MEMORY_HARNESS; value set as 'Claude-Code' (uppercase) instead of 'claude-code'; mcp config missing the env block.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/aacc7f63fa4ecee5. Report an issue: GitHub.

Appendix: source

Thrown at scripts/memory-mcp.mjs:178

  }
}

function isRecord(value) {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}

function isValidRequestId(value) {
  return (
    (typeof value === 'string' && value.length > 0 && value.length <= 128)
    || (typeof value === 'number' && Number.isSafeInteger(value))
  );
}

function resolveServiceSecurity(options = {}) {
  const env = isRecord(options.env) ? options.env : process.env;
  const harness = options.harness ?? env.ECC_MEMORY_HARNESS;
  if (typeof harness !== 'string' || !SLUG_REGEXP.test(harness)) {
    throw new Error(
      'ECC_MEMORY_HARNESS must identify this MCP server with a lowercase harness slug.'
    );
  }
  return Object.freeze({
    harness,
    allowUserScope: options.allowUserScope ?? env.ECC_MEMORY_ALLOW_USER_SCOPE === '1',
  });
}

function assertScopesAuthorized(scopes, security) {
  const requestedScopes = scopes || DEFAULT_RECALL_SCOPES;
  if (!security.allowUserScope && requestedScopes.includes('user')) {
    throw new JsonRpcError(
      -32602,
      'The user memory scope is disabled for this MCP server.'
    );
  }
  return requestedScopes;

View on GitHub (pinned to 8321021c54)