santifer/career-ops · error · Error

no local H-1B index and no H1B_API_BASE. Install the index w

Error message

no local H-1B index and no H1B_API_BASE. Install the index with: node plugins/h1b-sponsor/install-h1b-index.mjs (about 8 MiB of public DOL data; lookups then stay on this machine). To use an HTTP endpoint instead, set H1B_API_BASE to one you trust.

What it means

selectBackend() resolves where H-1B employer lookups run: a local DOL data index or a remote HTTP endpoint (H1B_API_BASE). If neither is available — no installed local index and no API base configured — it throws this error with complete remediation instructions. The plugin deliberately requires an explicit choice between local privacy-preserving lookups and a trusted HTTP endpoint.

Source

Thrown at plugins/h1b-sponsor/check.mjs:80

      opts: token ? { token } : {},
      resolveEmployer: httpBackend.resolveEmployer,
      searchEmployers: httpBackend.searchEmployers,
      getEmployerProfile: httpBackend.getEmployerProfile,
    };
  }
  if (localBackend.hasIndex()) {
    return {
      kind: 'index',
      // The index digest, so a cached answer is tied to the exact data that
      // produced it and a refreshed index invalidates the old numbers.
      source: await localBackend.indexSource(),
      opts: {},
      resolveEmployer: localBackend.resolveEmployer,
      searchEmployers: localBackend.searchEmployers,
      getEmployerProfile: localBackend.getEmployerProfile,
    };
  }
  throw new Error(
    'no local H-1B index and no H1B_API_BASE. Install the index with: node plugins/h1b-sponsor/install-h1b-index.mjs '
    + '(about 8 MiB of public DOL data; lookups then stay on this machine). To use an HTTP endpoint instead, '
    + 'set H1B_API_BASE to one you trust.',
  );
}

// Where the answer came from, reported back to the caller. The HTTP path names
// the employer's own URL so the number can be checked by hand; the local path
// names the index build, which is the equivalent handle for data on disk.
function sourceRef(employerId) {
  if (!backend) return null;
  if (backend.kind === 'index') return backend.source;
  return employerId
    ? `${backend.source}/employers/${encodeURIComponent(employerId)}`
    : `${backend.source}/employers`;
}

// Text from the backend goes through this before any non-JSON output, whether

View on GitHub (pinned to 1696bec4d0)

Solutions

1. Run: node plugins/h1b-sponsor/install-h1b-index.mjs to install the ~8 MiB public DOL index locally.
2. Alternatively set H1B_API_BASE in .env to an H-1B lookup endpoint you trust.
3. Verify the install actually wrote the index files (check for the data directory under plugins/h1b-sponsor).
4. In CI/deployment, add the install step (or the env var) to your pipeline before any scan that uses the plugin.

Example fix

# before (.env) — nothing set, index missing
# after: either install
#   node plugins/h1b-sponsor/install-h1b-index.mjs
# or set:
H1B_API_BASE=https://my-trusted-h1b-lookup.example.com

import { existsSync } from 'node:fs';
const hasIndex = existsSync('plugins/h1b-sponsor/index-data');
if (!hasIndex && !process.env.H1B_API_BASE) {
  console.error('Run: node plugins/h1b-sponsor/install-h1b-index.mjs (or set H1B_API_BASE)');
}

try {
  const backend = await selectBackend();
} catch (e) {
  if (e.message.includes('no local H-1B index')) {
    console.error('Install the index: node plugins/h1b-sponsor/install-h1b-index.mjs');
    return null;
  }
  throw e;
}

When it happens

Trigger: Calling selectBackend (and thus any check/lookup flow) when the local index files are absent and the H1B_API_BASE environment variable is unset, so neither backend can be constructed.

Common situations: Fresh clone where install-h1b-index.mjs was never run; the index data directory deleted or gitignored and lost; deploying to CI where the ~8 MiB install step was skipped; user expected a hosted API but never set H1B_API_BASE.

Related errors

• H1B_INDEX_PATH is set but empty. Unset it to use the default
• No "Applications" database found under the Career Ops page —
• [models] Failed to fetch free model list: ${reason}. OPENROU
• OPENROUTER_API_KEY not found. Copy .env.example to .env and
• portals.yml not found

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