heygen-com/hyperframes · error · AudioFxChainError

Chain file is missing a `nodes` array.

Error message

Chain file is missing a `nodes` array.

What it means

After version checks pass, parseAudioFxChain() requires obj.nodes to be an Array. A missing nodes field, or nodes set to an object/scalar, is rejected. The nodes array is the core payload of a chain — without it there is nothing to render.

Source

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

 * 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. Ensure the object has a top-level "nodes" key whose value is a JSON array (empty array [] is valid and yields a pass-through chain).
2. Use serializeAudioFxChain to emit the correct key.

Example fix

// before
parseAudioFxChain('{ "version": 1, "effects": [] }'); // missing `nodes`

// after
parseAudioFxChain('{ "version": 1, "nodes": [] }');

const parsed = JSON.parse(json);
if (!Array.isArray(parsed?.nodes)) throw new Error('chain missing nodes array');

function hasNodesArray(raw: unknown): raw is { nodes: unknown[] } {
  return typeof raw === "object" && raw !== null && Array.isArray((raw as any).nodes);
}

try { parseAudioFxChain(json); }
catch (err) { if (/missing a .nodes. array/.test(String(err))) { /* add nodes: [] */ } else throw err; }

When it happens

Trigger: A chain object that omits nodes entirely ({ version: 1 }); nodes spelled incorrectly (e.g. "node" or "effects"); nodes set to an object or single node instead of an array.

Common situations: Manual authoring with a typo'd key; a file truncated after the version field; confusion about the schema key name.

Related errors

• Chain file must be a JSON object.
• Node ${i} is not an object.
• Chain file is not valid JSON: ${(err as Error).message}
• Unsupported chain version: ${String(obj.version)}
• 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/8b23e6015bf71b7b. Report an issue: GitHub.