thedotmack/claude-mem · error · Error

Invalid CLAUDE_MEM_WORKER_PORT in settings.json: missing

Error message

Invalid CLAUDE_MEM_WORKER_PORT in settings.json: missing

What it means

Thrown by parseWorkerPort() in the export-memories script when the CLAUDE_MEM_WORKER_PORT setting read from ~/.claude-mem/settings.json is not a non-empty string. The export script needs this port to build the worker base URL (http://localhost:<port>), so a missing/blank value makes every downstream HTTP call impossible. The guard runs before any network activity, so this is a pure configuration precondition failure.

Source

Thrown at scripts/export-memories.ts:20

import { writeFileSync } from 'fs';
import { join } from 'path';
import { pathToFileURL } from 'url';
import { SettingsDefaultsManager } from '../src/shared/SettingsDefaultsManager.js';
import { resolveDataDir } from '../src/shared/paths.js';
import type {
  ObservationRecord,
  SdkSessionRecord,
  SessionSummaryRecord,
  UserPromptRecord,
  ExportData
} from './types/export.js';

const WORKER_FETCH_TIMEOUT_MS = 30_000;

function parseWorkerPort(rawPort: unknown): number {
  if (typeof rawPort !== 'string' || rawPort.trim() === '') {
    throw new Error('Invalid CLAUDE_MEM_WORKER_PORT in settings.json: missing');
  }

  const normalized = rawPort.trim();
  const port = Number.parseInt(normalized, 10);
  if (!Number.isInteger(port) || port < 1 || port > 65535 || String(port) !== normalized) {
    throw new Error(`Invalid CLAUDE_MEM_WORKER_PORT in settings.json: ${rawPort}`);
  }
  return port;
}

async function fetchWithTimeout(url: string, init?: RequestInit): Promise<Response> {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), WORKER_FETCH_TIMEOUT_MS);

  try {
    return await fetch(url, {
      ...init,
      signal: controller.signal,

View on GitHub (pinned to d768ba3643)

Solutions

  1. Start the claude-mem worker so it populates settings.json with CLAUDE_MEM_WORKER_PORT, then re-run the export.
  2. Inspect ~/.claude-mem/settings.json and confirm CLAUDE_MEM_WORKER_PORT exists; if missing, run the install/server command that writes it.
  3. If settings.json is empty or malformed, run the standard setup flow (npx claude-mem install / server start) to regenerate it.
  4. As a last resort, manually add "CLAUDE_MEM_WORKER_PORT": "<port>" to ~/.claude-mem/settings.json matching the port the worker is actually bound to.

Example fix

// before — settings.json missing the key
{}
// after
{ "CLAUDE_MEM_WORKER_PORT": "44328" }
Defensive patterns

Strategy: validation

Validate before calling

import { existsSync, readFileSync } from 'fs';
const p = join(resolveDataDir(), 'settings.json');
if (!existsSync(p)) throw new Error('Run the worker first to populate settings.json');
const s = JSON.parse(readFileSync(p, 'utf-8'));
if (typeof s.CLAUDE_MEM_WORKER_PORT !== 'string' || s.CLAUDE_MEM_WORKER_PORT.trim() === '') {
  throw new Error('CLAUDE_MEM_WORKER_PORT missing in settings.json');
}

Type guard

function isNonEmptyString(v: unknown): v is string {
  return typeof v === 'string' && v.trim() !== '';
}

Try / catch

try {
  const port = parseWorkerPort(settings.CLAUDE_MEM_WORKER_PORT);
} catch (e) {
  if (e instanceof Error && e.message.includes('missing')) {
    console.error('Start the worker so it writes the port, then retry.');
    process.exit(1);
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling exportMemories() (or running `tsx scripts/export-memories.ts ...`) when settings.json has no CLAUDE_MEM_WORKER_PORT key, has it set to null/undefined, set to a number instead of a string, or set to a whitespace-only string. Also fires when SettingsDefaultsManager.loadFromFile returns an object lacking the key because the file is empty or the worker was never started.

Common situations: First-time use before the worker has been started (the worker normally writes its port into settings.json on boot). A settings.json that was hand-edited and the key was deleted. Running the export script on a machine where claude-mem was only partially installed. A fresh data dir (~/.claude-mem) with no settings.json yet.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/8c9ee1dd201fd8cd. Report an issue: GitHub.