Invalid " ". Expected one of: full, symbol, none.

Error message

Invalid ${CONTENT_RETENTION_ENV} "${raw}". Expected one of: full, symbol, none.

What it means

Thrown by contentRetentionFromEnvironment when the GITNEXUS_CONTENT_RETENTION environment variable is set to a value other than 'full', 'symbol', or 'none'. The library validates the enum strictly at startup so an invalid retention mode never silently changes index storage behavior. Unset or empty values default to 'full'.

Solutions

Set GITNEXUS_CONTENT_RETENTION to exactly one of: full, symbol, none (lowercase).
Unset the variable entirely to get the default 'full' retention.
Check your .env / CI secret / shell profile for the misspelled value.

Example fix

// before (.env)
GITNEXUS_CONTENT_RETENTION=Symbols
// after (.env)
GITNEXUS_CONTENT_RETENTION=symbol

Defensive patterns

Strategy: validation

Validate before calling

const raw = process.env.GITNEXUS_CONTENT_RETENTION;
if (raw !== undefined && !['full', 'symbol', 'none'].includes(raw.trim())) {
  throw new Error(`GITNEXUS_CONTENT_RETENTION must be full|symbol|none, got "${raw}"`);
}

Type guard

const isContentRetention = (v: unknown): v is 'full' | 'symbol' | 'none' =>
  v === 'full' || v === 'symbol' || v === 'none';

Try / catch

try {
  retention = contentRetentionFromEnvironment();
} catch (err) {
  console.error(err.message);
  process.exitCode = 1;
}

Prevention

Only use exact lowercase values: full, symbol, none
Validate the env var in CI config linting before deploy
Prefer unsetting the variable over guessing values — default is 'full'

When it happens

Trigger: Setting GITNEXUS_CONTENT_RETENTION to any string other than exactly 'full', 'symbol', or 'none' (e.g. 'Full', 'FULL', 'symbols', '1') and then initializing repo content-retention settings.

Common situations: Typo or casing mistakes in shell profiles / CI env config; copying a value like 'symbol ' with stray whitespace is fine (trimmed), but 'sybmol' is not; docs from older versions using different names.

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 abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-15). Data as JSON: /api/errors/8e98f7a6d614478d. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/core/content-retention.ts:17

import fs from 'node:fs/promises';
import type { KnowledgeGraph } from './graph/types.js';
import {
  CONTENT_RETENTION_SCHEMA_VERSION,
  type ContentRetention,
  type FtsProfile,
  type RepoMeta,
} from '../storage/repo-meta.js';

export const CONTENT_RETENTION_ENV = 'GITNEXUS_CONTENT_RETENTION';

export const contentRetentionFromEnvironment = (): ContentRetention => {
  const raw = process.env[CONTENT_RETENTION_ENV];
  if (raw === undefined || raw.trim() === '') return 'full';
  const value = raw.trim();
  if (value === 'full' || value === 'symbol' || value === 'none') return value;
  throw new Error(
    `Invalid ${CONTENT_RETENTION_ENV} "${raw}". Expected one of: full, symbol, none.`,
  );
};

export const contentRetentionFromMeta = (
  meta: Pick<RepoMeta, 'contentRetention'> | null | undefined,
): ContentRetention => {
  const retention = meta?.contentRetention;
  if (retention === undefined || retention === 'full') return 'full';
  if (retention === 'symbol' || retention === 'none') return retention;
  // Legacy metadata has no field; an explicit unknown value is corrupt and must not expose text.
  return 'none';
};

export const ftsProfileForContentRetention = (retention: ContentRetention): FtsProfile => {
  switch (retention) {
    case 'symbol':
      return 'symbol-no-file-content';

View on GitHub (pinned to ac9a4e9abd)