rohitg00/agentmemory · error · Error

${envName} must be a positive integer, got: ${override}

Error message

${envName} must be a positive integer, got: ${override}

What it means

`resolveDimensions` in src/providers/embedding/_dimensions.ts parses an environment-variable override for the embedding vector size and throws when the value is non-numeric or <= 0. Without a valid override it falls back to model-specific lookup or DEFAULT_DIMENSIONS, so this error only fires when an override is present but invalid.

Source

Thrown at src/providers/embedding/_dimensions.ts:39

const DEFAULT_DIMENSIONS = 1536;

function lookupModelDimensions(model: string): number | undefined {
  if (model in MODEL_DIMENSIONS) return MODEL_DIMENSIONS[model];
  const slash = model.indexOf("/");
  if (slash === -1) return undefined;
  const bare = model.slice(slash + 1);
  return MODEL_DIMENSIONS[bare];
}

export function resolveDimensions(
  model: string,
  override: string | undefined,
  envName: string,
): number {
  if (override !== undefined && override.trim().length > 0) {
    const parsed = parseInt(override, 10);
    if (!Number.isFinite(parsed) || parsed <= 0) {
      throw new Error(
        `${envName} must be a positive integer, got: ${override}`,
      );
    }
    return parsed;
  }
  return lookupModelDimensions(model) ?? DEFAULT_DIMENSIONS;
}

export { MODEL_DIMENSIONS, DEFAULT_DIMENSIONS };

View on GitHub (pinned to e04ba88819)

Solutions

1. Set the env var to a plain positive integer, e.g. `EMBEDDING_DIMENSIONS=1024`.
2. Unset the variable entirely so resolveDimensions uses the model's known dimensions or DEFAULT_DIMENSIONS.
3. Check for stray characters: no units (px), decimals (1024.0), exponents (1e3), quotes, or trailing spaces are accepted by parseInt-based parsing.
4. Verify in the error message which env name (envName) is offending, and fix that specific variable in your shell profile/.env.

Example fix

// before
process.env.EMBEDDING_DIMENSIONS = "1024.0"; // throws
// after
process.env.EMBEDDING_DIMENSIONS = "1024";
// or simply delete the override:
delete process.env.EMBEDDING_DIMENSIONS;

function validateDimensionsEnv(name: string): number | undefined {
  const raw = process.env[name];
  if (raw === undefined || raw.trim() === "") return undefined;
  const n = Number(raw);
  if (!Number.isInteger(n) || n <= 0) throw new Error(`${name} must be a positive integer, got: ${raw}`);
  return n;
}
validateDimensionsEnv("EMBEDDING_DIMENSIONS"); // run before constructing providers

function isPositiveIntString(v: string): boolean {
  return /^\d+$/.test(v.trim()) && parseInt(v, 10) > 0;
}

try {
  provider = createEmbeddingProvider();
} catch (e) {
  if (e instanceof Error && e.message.includes("must be a positive integer")) {
    console.warn("Bad dimensions override; falling back to model defaults");
    delete process.env.EMBEDDING_DIMENSIONS;
    provider = createEmbeddingProvider();
  } else throw e;
}

When it happens

Trigger: Constructing any embedding provider whose dimensions override is read from an env var (the envName in the message) when that variable is set to e.g. "abc", "", whitespace is skipped but "0", "-768", "3.5", or "1e3" — anything parseInt can't turn into a positive integer.

Common situations: Typo like `EMBEDDING_DIMENSIONS=768px`; shell exported an empty-ish or zero value; copying a float like `1024.0` from docs; CI secrets set to placeholder text like `changeme`; confusing dimensions with tokens/API key in the env config.

Related errors

• COHERE_API_KEY is required
• GEMINI_API_KEY is required
• Invalid dateFrom: ${filter.dateFrom}
• Invalid dateTo: ${filter.dateTo}
• Refusing to read image outside managed store: ${data.raw.ima

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