heygen-com/hyperframes · error · AudioFxChainError

Unsupported chain version: ${String(obj.version)}

Error message

Unsupported chain version: ${String(obj.version)}

What it means

parseAudioFxChain() requires obj.version to exactly equal HF_AUDIO_FX_CHAIN_VERSION (currently 1). Any other value — a different number, a string, undefined, or null — is rejected. Chain files are explicitly versioned so a reader refuses a version it cannot interpret, preventing a future/incompatible chain from rendering with wrong semantics. The bad value is interpolated via String().

Source

Thrown at packages/core/src/audioFx.ts:772

/**
 * Parse a chain file. Unknown effect ids are rejected rather than skipped: a
 * chain that silently loses a node would render differently from the project
 * the author saved, which is worse than refusing to render at all.
 */
export function parseAudioFxChain(json: string): HfAudioFxChain {
  let raw: unknown;
  try {
    raw = JSON.parse(json);
  } catch (err) {
    throw new AudioFxChainError(`Chain file is not valid JSON: ${(err as Error).message}`);
  }
  if (typeof raw !== "object" || raw === null) {
    throw new AudioFxChainError("Chain file must be a JSON object.");
  }
  const obj = raw as { version?: unknown; nodes?: unknown };
  if (obj.version !== HF_AUDIO_FX_CHAIN_VERSION) {
    throw new AudioFxChainError(`Unsupported chain version: ${String(obj.version)}`);
  }
  if (!Array.isArray(obj.nodes)) {
    throw new AudioFxChainError("Chain file is missing a `nodes` array.");
  }
  const nodes: HfAudioFxNode[] = obj.nodes.map((n, i) => {
    if (typeof n !== "object" || n === null) {
      throw new AudioFxChainError(`Node ${i} is not an object.`);
    }
    const node = n as { type?: unknown; enabled?: unknown; params?: unknown };
    if (typeof node.type !== "string" || !BY_ID.has(node.type)) {
      throw new AudioFxChainError(`Node ${i} has unknown effect type: ${String(node.type)}`);
    }
    return {
      type: node.type,
      enabled: node.enabled !== false,
      params: normalizeAudioFxParams(
        node.type,
        (node.params ?? undefined) as HfAudioFxParamValues | undefined,

View on GitHub (pinned to c2996c8626)

Solutions

1. Set "version" to the exact value of HF_AUDIO_FX_CHAIN_VERSION (1) — use the exported constant, do not hard-code.
2. Upgrade the rendering HyperFrames to match or exceed the version that wrote the chain.
3. If you genuinely need to migrate an older chain shape, write a one-time transform that rewrites it to the current version before parseAudioFxChain.

Example fix

// before
parseAudioFxChain('{ "version": 2, "nodes": [] }'); // Unsupported chain version: 2

// after — pin to the exported version constant
import { HF_AUDIO_FX_CHAIN_VERSION } from "@hyperframes/core";
const json = JSON.stringify({ version: HF_AUDIO_FX_CHAIN_VERSION, nodes: [] });
parseAudioFxChain(json);

import { HF_AUDIO_FX_CHAIN_VERSION } from "@hyperframes/core";
const parsed = JSON.parse(json);
if (parsed.version !== HF_AUDIO_FX_CHAIN_VERSION) {
  throw new Error(`chain version ${parsed.version} != supported ${HF_AUDIO_FX_CHAIN_VERSION}`);
}

import { HF_AUDIO_FX_CHAIN_VERSION } from "@hyperframes/core";
function hasMatchingVersion(raw: unknown): boolean {
  return typeof raw === "object" && raw !== null && (raw as any).version === HF_AUDIO_FX_CHAIN_VERSION;
}

try { parseAudioFxChain(json); }
catch (err) { if (/Unsupported chain version/.test(String(err))) { /* set version to HF_AUDIO_FX_CHAIN_VERSION or upgrade */ } else throw err; }

When it happens

Trigger: Loading a chain file written by a newer HyperFrames (version 2+) on an older runtime; a hand-written file omitting the version field (undefined); a file with version as a string '1' instead of number 1; a file from a different tool that uses its own versioning.

Common situations: Version skew between the studio that authored the chain and the renderer; manual authoring that forgets the version key; copy-pasting a chain from docs that target a different version.

Related errors

• Chain file is not valid JSON: ${(err as Error).message}
• Chain file must be a JSON object.
• Chain file is missing a `nodes` array.
• Node ${i} is not an object.
• Node ${i} has unknown effect type: ${String(node.type)}

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