CloakHQ/CloakBrowser · error · Error

HTTP ${response.status}

Error message

HTTP ${response.status}

What it means

downloadGeoipDb received a non-2xx HTTP status (or no body) when fetching the GeoIP database URL, and throws `HTTP <status>` to abort the download before writing a bad file.

Source

Thrown at js/src/geoip.ts:380

    // Another concurrent launch may have owned the download; reuse its result.
    return fs.existsSync(dbPath) ? dbPath : null;
  } catch {
    return null;
  }
}

async function downloadGeoipDb(dest: string): Promise<void> {
  const dir = path.dirname(dest);
  fs.mkdirSync(dir, { recursive: true });
  console.log("[cloakbrowser] Downloading GeoIP database (~70 MB)…");

  const tmpPath = `${dest}.tmp.${Date.now()}`;
  try {
    const response = await fetch(GEOIP_DB_URL, {
      redirect: "follow",
    });
    if (!response.ok || !response.body) {
      throw new Error(`HTTP ${response.status}`);
    }

    const fileStream = createWriteStream(tmpPath);
    const reader = response.body.getReader();

    for (;;) {
      const { done, value } = await reader.read();
      if (done) break;
      fileStream.write(value);
    }

    await new Promise<void>((resolve, reject) => {
      fileStream.end(() => resolve());
      fileStream.on("error", reject);
    });

    fs.renameSync(tmpPath, dest);
    console.log(`[cloakbrowser] GeoIP database ready: ${dest}`);

View on GitHub (pinned to d6bad5de26)

Solutions

1. Retry the download after a delay (429/5xx are often transient) with backoff
2. Check the GEOIP_DB_URL constant/endpooint is still valid and licensed (MaxMind requires account/license keys for GeoLite2)
3. Bypass or configure corporate proxy env vars (HTTPS_PROXY) if a 407/403 intercept page is returned
4. Vendor or manually place the .mmdb file and skip runtime download

Example fix

// before
await downloadGeoipDb(dest);

// after
for (let attempt = 1; attempt <= 3; attempt++) {
  try { await downloadGeoipDb(dest); break; }
  catch (e) {
    if (attempt === 3) throw e;
    await sleep(attempt * 2000);
  }
}

null

function isHttpDownloadError(e: unknown): e is Error {
  return e instanceof Error && /^HTTP \d{3}$/.test(e.message);
}

for (let a = 1; a <= 3; a++) {
  try { await downloadGeoipDb(dest); break; }
  catch (e) {
    if (a === 3 || !isHttpDownloadError(e)) throw e;
    await new Promise(r => setTimeout(r, a * 2000));
  }
}

When it happens

Trigger: The fetch to GEOIP_DB_URL returns 403/404/429/5xx, or response.body is null (e.g. a redirect chain ending without a body despite redirect: 'follow').

Common situations: Rate-limited or expired CDN links, license-key-protected MaxMind endpoints without credentials, corporate proxies returning 407, or transient 5xx outages at the mirror.

Related errors

• GeoIP resolution failed: could not discover the egress IP
• GeoIP resolution failed: GeoIP database is unavailable
• GeoIP lookup failed for ${ip}: ${detail}
• GeoIP resolution failed: could not determine ${missing.join(
• Pro download completed but binary not found at: {p}

AI-assisted analysis of CloakHQ/CloakBrowser@d6bad5de26 (2026-08-28). Data as JSON: /api/errors/8856f115a2e6060d. Report an issue: GitHub.