What causes "Invalid ${envName}, using default" in thedotmack/claude-mem?

Set the variable to a bare integer in milliseconds within the logged min/max (e.g. 10000 for ten seconds).

Invalid ${envName}, using default

Error message

Invalid ${envName}, using default

What it means

readTimeoutEnv parses worker timeout env vars (e.g. CLAUDE_MEM_HEALTH_TIMEOUT_MS) as integers and bounds-checks them against [min, max]. If the value is non-numeric or outside bounds, it warns with the value and the bounds, then falls back to the default derived from HOOK_TIMEOUTS.

Source

Thrown at src/shared/worker-utils.ts:31

// Imported from ProcessManager.js directly (not the infrastructure barrel):
// tests mock the barrel module wholesale, and the resolver must stay real.
// ProcessManager imports nothing from worker-utils, so no cycle.
import { resolveWorkerRuntimePath } from "../services/infrastructure/ProcessManager.js";
import { acquireSpawnLock, releaseSpawnLock } from "./worker-spawn-gate.js";
import { killProcessTree } from "./kill-process-tree.js";

function readTimeoutEnv(
  envName: string,
  defaultValue: number,
  bounds: { min: number; max: number }
): number {
  const envVal = process.env[envName];
  if (envVal) {
    const parsed = parseInt(envVal, 10);
    if (Number.isFinite(parsed) && parsed >= bounds.min && parsed <= bounds.max) {
      return parsed;
    }
    logger.warn('SYSTEM', `Invalid ${envName}, using default`, {
      value: envVal, min: bounds.min, max: bounds.max
    });
  }
  return defaultValue;
}

const HEALTH_CHECK_TIMEOUT_MS = readTimeoutEnv(
  'CLAUDE_MEM_HEALTH_TIMEOUT_MS',
  getTimeout(HOOK_TIMEOUTS.HEALTH_CHECK),
  { min: 500, max: 300000 }
);

const HOOK_READINESS_TIMEOUT_MS = readTimeoutEnv(
  'CLAUDE_MEM_HOOK_READINESS_TIMEOUT_MS',
  getTimeout(HOOK_TIMEOUTS.HOOK_READINESS_WAIT),
  { min: 0, max: 300000 }
);

View on GitHub (pinned to 8bc631a71a)

Solutions

Set the variable to a bare integer in milliseconds within the logged min/max (e.g. 10000 for ten seconds).
Or unset the variable entirely to inherit the default.
Double-check for stray quotes or units in the env value.

Example fix

# before
export CLAUDE_MEM_HEALTH_TIMEOUT_MS=10s

# after
export CLAUDE_MEM_HEALTH_TIMEOUT_MS=10000

Defensive patterns

Strategy: validation

Validate before calling

const parsed = parseInt(process.env.CLAUDE_MEM_HEALTH_TIMEOUT_MS ?? '', 10);
if (!Number.isFinite(parsed) || parsed < 500 || parsed > 300000) {
  // fall back to default; do not ship the raw value further
}

Type guard

const isBoundedInt = (v: string, min: number, max: number): v is `${number}` => {
  const n = parseInt(v, 10);
  return Number.isFinite(n) && n >= min && n <= max;
};

Prevention

Set timeout env vars as bare integers in milliseconds (10000, not '10s').
Lint shell profiles and CI env blocks for unit suffixes in numeric env vars.
Remember bounds are enforced (e.g. 500..300000); values outside them silently become defaults.

When it happens

Trigger: Setting CLAUDE_MEM_HEALTH_TIMEOUT_MS (or a sibling timeout var) to a non-integer like "2s"/"abc", or a number outside the logged min/max window (e.g. 100 when min is 500, or 999999 above max).

Common situations: Copying "10s"-style values from docs into env vars; confusing seconds with milliseconds; pasting values from older versions with different bounds.

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 thedotmack/claude-mem@8bc631a71a (2026-08-20). Data as JSON: /api/errors/cc554196be395843. Report an issue: GitHub.