abhigyanpatwari/GitNexus · error

embedding device must be one of auto, dml, cuda, cpu, wasm…

Error message

embedding device must be one of auto, dml, cuda, cpu, wasm; got "${value}"

What it means

GITNEXUS_EMBEDDING_DEVICE must be one of the enumerated execution backends — auto, dml (Windows DirectML), cuda (NVIDIA), cpu, or wasm. parseDevice() rejects every other spelling with this error. The allow-list exists because the value is passed straight to transformers.js/ONNX session options, and a silently passed typo would surface later as an opaque ONNX failure.

Solutions

1. Use exactly one of the five values, lowercase: export GITNEXUS_EMBEDDING_DEVICE=cuda.
2. Use auto to let the runtime pick the best available backend.
3. Trim stray whitespace/quotes from .env values (value.trim() is not applied here).
4. For Apple Silicon, prefer auto — the wasm/cpu path is chosen appropriately; there is no 'metal' option.

Example fix

# before
export GITNEXUS_EMBEDDING_DEVICE=gpu
npx gitnexus analyze --embeddings
# embedding device must be one of auto, dml, cuda, cpu, wasm; got "gpu"

# after
export GITNEXUS_EMBEDDING_DEVICE=auto
npx gitnexus analyze --embeddings

const EMBEDDING_DEVICES = new Set(['auto', 'dml', 'cuda', 'cpu', 'wasm']);
function embeddingDeviceValid(v: string | undefined): boolean {
  return v === undefined || EMBEDDING_DEVICES.has(v);
}
if (!embeddingDeviceValid(process.env.GITNEXUS_EMBEDDING_DEVICE)) {
  throw new Error(`GITNEXUS_EMBEDDING_DEVICE must be one of: ${[...EMBEDDING_DEVICES].join(', ')}`);
}

function isEmbeddingDevice(v: unknown): v is 'auto' | 'dml' | 'cuda' | 'cpu' | 'wasm' {
  return typeof v === 'string' && ['auto', 'dml', 'cuda', 'cpu', 'wasm'].includes(v);
}

try {
  await runWithEmbeddings();
} catch (err) {
  if (String((err as Error).message).includes('embedding device must be one of')) {
    process.env.GITNEXUS_EMBEDDING_DEVICE = 'auto';
    return runWithEmbeddings();
  }
  throw err;
}

When it happens

Trigger: Setting GITNEXUS_EMBEDDING_DEVICE to anything outside {auto,dml,cuda,cpu,wasm} — e.g. 'gpu', 'metal', 'CUDA' (uppercase), 'CUDA:1', 'rocm' — then initializing local embeddings (getOrCreateEmbedder / analyze --embeddings without an HTTP URL).

Common situations: Users guessing device names from other ML tools ('metal' on macOS, 'gpu'), uppercase spellings copied from docs of other frameworks, or trailing whitespace/quotes surviving from .env files.

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

• must be a positive integer, got
• GITNEXUS_EMBEDDING_DIMS must be a positive integer, got
• GITNEXUS_EMBEDDING_REQUEST_DIMS must be a positive integer…
• must be a non-negative integer, got
• must be a non-negative integer <= , got

AI-assisted analysis of abhigyanpatwari/GitNexus@aac7515d2a (2026-08-20). Data as JSON: /api/errors/ac74a6c7cefe4fe7. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/core/embeddings/config.ts:71

  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new Error(`${name} must be a positive integer, got "${value}"`);
  }
  return parsed;
};

const parseDevice = (value: string | undefined): EmbeddingConfig['device'] | undefined => {
  if (value === undefined) return undefined;
  if (
    value === 'auto' ||
    value === 'dml' ||
    value === 'cuda' ||
    value === 'cpu' ||
    value === 'wasm'
  ) {
    return value;
  }
  throw new Error(`embedding device must be one of auto, dml, cuda, cpu, wasm; got "${value}"`);
};

export const resolveEmbeddingConfig = (
  overrides: Partial<EmbeddingConfig> = {},
): EmbeddingConfig => {
  const env = process.env;
  return {
    ...DEFAULT_EMBEDDING_CONFIG,
    ...overrides,
    batchSize: parsePositiveInt(
      'GITNEXUS_EMBEDDING_BATCH_SIZE',
      env.GITNEXUS_EMBEDDING_BATCH_SIZE,
      overrides.batchSize ?? DEFAULT_EMBEDDING_CONFIG.batchSize,
    ),
    subBatchSize: parsePositiveInt(
      'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
      env.GITNEXUS_EMBEDDING_SUB_BATCH_SIZE,
      overrides.subBatchSize ?? DEFAULT_EMBEDDING_CONFIG.subBatchSize,

View on GitHub (pinned to aac7515d2a)