heygen-com/hyperframes · error · AudioFxChainError

Chain file is not valid JSON: ${(err as Error).message}

Error message

Chain file is not valid JSON: ${(err as Error).message}

What it means

parseAudioFxChain() wraps JSON.parse in a try/catch and re-throws as AudioFxChainError when the chain file string is not valid JSON. The original parse error message is interpolated. This is the first validation gate when loading a serialized chain (the data-fx-chain attribute or a chain file).

Source

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

export class AudioFxChainError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "AudioFxChainError";
  }
}

/**
 * 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)}`);

View on GitHub (pinned to c2996c8626)

Solutions

1. Validate the string with JSON.parse in a scratch script or a JSON linter before feeding it to parseAudioFxChain.
2. Regenerate the chain via serializeAudioFxChain(chain) rather than hand-writing JSON.
3. If editing by hand, fix the cited syntax error in the interpolated message (it names the position).

Example fix

// before
const chain = parseAudioFxChain('{ "version": 1, "nodes": [ }'); // trailing comma / missing object

// after — produce the JSON programmatically
import { serializeAudioFxChain } from "@hyperframes/core";
const attr = serializeAudioFxChain({ version: 1, nodes: [{ type: "highpass", params: { frequency: 1000 } }] });
const chain = parseAudioFxChain(attr);

function isValidChainJson(s: string): boolean {
  try { JSON.parse(s); return true; } catch { return false; }
}
if (!isValidChainJson(attr)) throw new Error('chain attribute is not valid JSON');

function isValidChainJson(s: string): boolean { try { JSON.parse(s); return true; } catch { return false; } }

import { parseAudioFxChain, AudioFxChainError } from "@hyperframes/core";
try { chain = parseAudioFxChain(json); }
catch (err) {
  if (err instanceof AudioFxChainError) { /* show err.message, regenerate via serializeAudioFxChain */ }
  else throw err;
}

When it happens

Trigger: Passing a malformed JSON string to parseAudioFxChain — unclosed brace, trailing comma, single quotes, unescaped characters, a truncated/cut-off string, or a chain attribute that was hand-edited and broke syntax.

Common situations: Manually editing the data-fx-chain attribute and introducing a syntax error; a build step mangling/escaping the attribute; reading a chain file that was partially written or corrupted on disk; copy-paste losing characters.

Related errors

• Chain file must be a JSON object.
• Unsupported chain version: ${String(obj.version)}
• 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/528a4ecada68a3a2. Report an issue: GitHub.