santifer/career-ops · error · Error

H1B_INDEX_PATH is set but empty. Unset it to use the default

Error message

H1B_INDEX_PATH is set but empty. Unset it to use the default index location.

What it means

indexPath() reads the H1B_INDEX_PATH environment variable. If the variable is defined but its value is empty or whitespace-only, the library cannot distinguish 'use default' from a misconfiguration, so it throws and tells you to unset the variable instead.

Source

Thrown at plugins/h1b-sponsor/lib/index.mjs:136

    drain() {
      trim();
      return items;
    },
  };
}

/**
 * Where the index lives. H1B_INDEX_PATH relocates it (a shared read-only copy,
 * a scratch fixture in the test suite). Present-but-blank is a misconfiguration
 * rather than "unset", exactly as H1B_API_BASE treats it: silently falling back
 * would read an index the user believed they had replaced.
 */
export function indexPath() {
  const raw = process.env.H1B_INDEX_PATH;
  if (raw === undefined) return DEFAULT_INDEX;
  const trimmed = String(raw).trim();
  if (!trimmed) {
    throw new Error('H1B_INDEX_PATH is set but empty. Unset it to use the default index location.');
  }
  return trimmed;
}

/** The sidecar install-h1b-index.mjs writes beside the index. */
export function metaPath(file = indexPath()) {
  return `${file}.meta.json`;
}

/** Whether a local index is installed. Decides the backend, so it never throws on a missing file. */
export function hasIndex(file = indexPath()) {
  return existsSync(file);
}

const SHA256_RE = /^[0-9a-f]{64}$/;
let cachedDigest = null;

/**

View on GitHub (pinned to 1696bec4d0)

Solutions

Remove the H1B_INDEX_PATH line (or comment it out) from .env / the environment so the default index location is used.
If you do want a custom path, set it to a real path: H1B_INDEX_PATH=/path/to/h1b-index.
In shell scripts, guard expansion: `[ -n "$VAR" ] && export H1B_INDEX_PATH="$VAR"`.

Example fix

// before (.env)
H1B_INDEX_PATH=
// after
# H1B_INDEX_PATH=/data/h1b/index.sqlite  (commented out = use default)

Defensive patterns

Strategy: validation

Validate before calling

// before launching the tool:
if (process.env.H1B_INDEX_PATH !== undefined && !process.env.H1B_INDEX_PATH.trim()) {
  delete process.env.H1B_INDEX_PATH; // or throw with instructions
}

Type guard

function hasUsableIndexPath(env = process.env) {
  return env.H1B_INDEX_PATH === undefined || env.H1B_INDEX_PATH.trim() !== '';
}

Try / catch

try {
  const profile = await getEmployerProfile(id);
} catch (e) {
  if (e.message.startsWith('H1B_INDEX_PATH is set but empty')) {
    console.error('Unset H1B_INDEX_PATH or give it a real path in .env.');
    return;
  }
  throw e;
}

Prevention

Comment out unused env keys entirely instead of leaving `KEY=` blanks in .env.
In shell wrappers, only export the variable when the source variable is non-empty.
Include empty-vs-unset env checks in deployment templates and CI linting.
Remember the convention: unset = default location, set = custom path; there is no valid empty state.

When it happens

Trigger: Calling indexPath() (directly or via metaPath/indexFile or any lookup using the index) when the environment has H1B_INDEX_PATH set to '' or only spaces — e.g. `H1B_INDEX_PATH= node script.mjs` or `export H1B_INDEX_PATH=""`.

Common situations: Docker/compose env entries like `H1B_INDEX_PATH=` in an .env file; a deploy template that comments out the value but leaves the key; a shell script doing `export H1B_INDEX_PATH=$SOME_VAR` where SOME_VAR is empty.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of santifer/career-ops@1696bec4d0 (2026-09-01). Data as JSON: /api/errors/7d7af2d194424a3c. Report an issue: GitHub.