heygen-com/hyperframes · error · Error

can't check skills freshness (GitHub manifest unreachable) —

Error message

can't check skills freshness (GitHub manifest unreachable) — refusing to report success. Retry when online.

What it means

Thrown by updateSkillsOffline in strict mode when nothing was requested and the GitHub manifest is unreachable. Offline, freshness is unknowable; a bare strict run (the documented `skills check || skills update` CI contract) must fail loudly rather than exit 0 while everything stays stale. Non-strict runs still presence-check the fallback core set and proceed.

Source

Thrown at packages/cli/src/commands/skills.ts:441

 * still succeed.
 *
 *   - Named run (`update <workflow>`): presence-check requested + fallback
 *     core, blind-install whatever is absent (a truly dead network fails the
 *     clone fast, and `strict` decides how loudly). Stale-but-present
 *     proceeds — blocking a build on a network hiccup is worse than running
 *     one release behind.
 *   - Bare run (nothing requested): the whole job was freshness, and presence
 *     can't prove it. strict — the documented `check || update` CI contract —
 *     must fail loudly rather than exit 0 while everything stays stale.
 *     Non-strict (init) still presence-checks the fallback core, so a fresh
 *     machine gets a best-effort core install instead of nothing.
 */
async function updateSkillsOffline(
  requested: readonly string[],
  opts: { strict: boolean; cwd?: string },
): Promise<UpdateSkillsResult> {
  if (requested.length === 0 && opts.strict) {
    throw new Error(
      "can't check skills freshness (GitHub manifest unreachable) — refusing to report success. Retry when online.",
    );
  }

  const targets = [...new Set([...requested, ...FALLBACK_CORE_SKILLS])];
  const present = new Set(presentSkills(targets, { cwd: opts.cwd }));
  const absent = targets.filter((name) => !present.has(name));

  console.log(
    c.dim(
      absent.length === 0
        ? "Skills freshness check unavailable (offline?) — installed skills found, continuing without a refresh."
        : `Skills freshness check unavailable (offline?) — attempting a blind install of: ${absent.join(", ")}`,
    ),
  );

  if (absent.length > 0) {
    await installSkills(absent, { cwd: opts.cwd, strict: opts.strict });

View on GitHub (pinned to c2996c8626)

Solutions

  1. Restore network access to raw.githubusercontent.com and retry
  2. If you must run offline, pass an explicit skill name so presence-checking kicks in instead of the strict freshness contract
  3. Run non-strict (init) which degrades gracefully to presence-checking the fallback core
  4. Configure proxy/allowlist for raw.githubusercontent.com in CI

Example fix

// before (CI, offline, fails)
hyperframes skills check
// after (online)
hyperframes skills check
// or scope to a skill so presence is checked
hyperframes skills update pr-to-video
Defensive patterns

Strategy: try-catch

Validate before calling

async function canReachManifest(): Promise<boolean> {
  try {
    await fetch("https://raw.githubusercontent.com/");
    return true;
  } catch { return false; }
}

Try / catch

try {
  await updateSkills([], { strict: true });
} catch (e) {
  if (e.message.includes("manifest unreachable")) {
    // degrade: pass an explicit skill, or run non-strict
  }
  throw e;
}

Prevention

When it happens

Trigger: updateSkillsOffline(requested, {strict:true}) with requested.length === 0 throws immediately at skills.ts:441. Reach updateSkillsOffline when the manifest fetch failed (raw.githubusercontent.com blocked, no network).

Common situations: CI running `hyperframes skills check` behind a corporate proxy that blocks raw.githubusercontent.com; offline dev machine; GitHub outage; DNS failure. Any context where the manifest can't be fetched AND the run is strict AND no specific skill was requested.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/704a622530ed5041. Report an issue: GitHub.