heygen-com/hyperframes · error · AudioFxChainError

Node ${i} has unknown effect type: ${String(node.type)}

Error message

Node ${i} has unknown effect type: ${String(node.type)}

What it means

For each node, parseAudioFxChain() requires node.type to be a string AND a key present in BY_ID (the HF_AUDIO_FX registry). Unknown ids are rejected rather than silently dropped, because a chain that loses a node would render differently from the project the author saved — failing loudly is safer than a wrong render. The offending index and type are interpolated.

Source

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

    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,
      ),
    };
  });
  return { version: HF_AUDIO_FX_CHAIN_VERSION, nodes };
}

/** The nodes that should process audio, in order. */
export function enabledAudioFxNodes(chain: HfAudioFxChain): HfAudioFxNode[] {
  return chain.nodes.filter((n) => n.enabled !== false);
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Use only ids present in HF_AUDIO_FX_IDS; cross-check against packages/core/src/audioFx.ts HF_AUDIO_FX.
2. Upgrade the renderer to a version that includes the effect, or substitute a supported effect.
3. Regenerate via serializeAudioFxChain so ids come straight from the registry.

Example fix

// before
parseAudioFxChain('{ "version": 1, "nodes": [ {"type":"compressor"} ] }'); // unknown -> 'worklet-compressor' is the real id

// after
import { HF_AUDIO_FX_IDS } from "@hyperframes/core";
const safeType = HF_AUDIO_FX_IDS.includes(node.type) ? node.type : "worklet-compressor";
parseAudioFxChain(JSON.stringify({ version: 1, nodes: [{ type: safeType }] }));

import { HF_AUDIO_FX_IDS } from "@hyperframes/core";
const known = new Set(HF_AUDIO_FX_IDS);
for (const n of nodes) if (typeof n.type !== "string" || !known.has(n.type)) throw new Error(`unknown effect type ${n.type}`);

import { HF_AUDIO_FX_IDS } from "@hyperframes/core";
const FX = new Set(HF_AUDIO_FX_IDS);
function isKnownFxNode(n: unknown): n is { type: string; params?: unknown } {
  return typeof n === "object" && n !== null && typeof (n as any).type === "string" && FX.has((n as any).type);
}

try { parseAudioFxChain(json); }
catch (err) { if (/unknown effect type/.test(String(err))) { /* map to a supported id */ } else throw err; }

When it happens

Trigger: A chain file referencing an effect id that doesn't exist: a typo ('higpass'), a removed id, an id from a newer HyperFrames version, or a node whose type is a number/boolean/null. Note this is stricter than buildFxNode's runtime check — it fires at load time.

Common situations: Hand-authored chain with a misspelled effect; version skew (newer studio wrote an id the older renderer doesn't know); a node missing the type field entirely.

Related errors

• Unknown effect type: ${type}
• Chain file is not valid JSON: ${(err as Error).message}
• Chain file must be a JSON object.
• Unsupported chain version: ${String(obj.version)}
• Chain file is missing a `nodes` array.

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