musistudio/claude-code-router · error · Error

Could not resolve host: ${hostname}

Error message

Could not resolve host: ${hostname}

What it means

resolveSafeAddress DNS-resolves the manifest host (dns.lookup with all:true) and throws when the lookup returns zero records. The manifest cannot be used because its host has no addresses to safety-check.

Source

Thrown at packages/core/src/providers/manifest-service.ts:242

  if (!normalized) {
    throw new Error(`${label} is invalid.`);
  }
  if (
    normalized === "localhost" ||
    normalized.endsWith(".localhost") ||
    normalized.endsWith(".home") ||
    normalized.endsWith(".lan") ||
    normalized.endsWith(".local") ||
    normalized.endsWith(".internal")
  ) {
    throw new Error(`${label} cannot target a local or internal host.`);
  }
}

async function resolveSafeAddress(hostname: string): Promise<SafeAddress> {
  const addresses = await lookup(hostname, { all: true, verbatim: true });
  if (addresses.length === 0) {
    throw new Error(`Could not resolve host: ${hostname}`);
  }

  for (const address of addresses) {
    if (!isPublicIpAddress(address.address)) {
      throw new Error(`Remote manifest host resolved to a private or reserved address: ${address.address}`);
    }
  }

  const first = addresses[0];
  return {
    address: first.address,
    family: first.family === 6 ? 6 : 4
  };
}

function isPublicIpAddress(address: string): boolean {
  const family = net.isIP(address);
  if (family === 4) {

View on GitHub (pinned to 99f24806c6)

Solutions

1. Fix the hostname spelling in the manifest/provider config
2. Verify DNS: `dig <host>` / `node -e "require('dns').lookup('host',{all:true},console.log)"` should return records
3. Wait for DNS propagation if the domain was just created or migrated
4. If the domain is truly gone, remove or replace the manifest reference

import { lookup } from 'node:dns/promises';
const addrs = await lookup(hostname, { all: true });
if (addrs.length === 0) throw new Error(`no DNS records for ${hostname}`);

catch (e) { if (e instanceof Error && e.message.startsWith('Could not resolve host')) return cachedManifest ?? null; }

When it happens

Trigger: validatePublicHttpsUrl calls resolveSafeAddress(hostname) and dns.lookup returns an empty array — typically NXDOMAIN handled by the resolver shim, or a resolver returning no A/AAAA records.

Common situations: Typos in the domain, stale/decommissioned manifest hosts, DNS propagation delays after moving the manifest, or restrictive resolvers returning empty answers.

Understand the failure class

• DNS resolution errors: ENOTFOUND and getaddrinfo failures — how hostname lookups fail and how to debug them.

Related errors

• Remote manifest host resolved to a private or reserved addre
• ${identityIssue.message}
• ${label} from a remote manifest must use https.
• ${label} cannot target a local or internal host.
• Claude App profiles do not support agent arguments.

AI-assisted analysis of musistudio/claude-code-router@99f24806c6 (2026-08-27). Data as JSON: /api/errors/987d99dc389a57cb. Report an issue: GitHub.