{"record":{"id":"6337d3b0127f542b","repo":"nexu-io/open-design","slug":"figma-import-failed","errorCode":"FIGMA_IMPORT_FAILED","errorMessage":"unexpected prelude \"${prelude}\"","messagePattern":"unexpected prelude \"(.+?)\"","errorType":"http","errorClass":"Error","httpStatus":400,"severity":"error","filePath":"apps/daemon/src/figma/fig-decode.ts","lineNumber":150,"sourceCode":"function hasFigPrelude(bytes: Uint8Array): boolean {\n  if (bytes.length < 8) return false;\n  const prelude = asciiAt(bytes, 0, 8);\n  return prelude === FIG_MAGIC || prelude === JAM_MAGIC;\n}\n\ninterface CompiledFigSchema {\n  decodeMessage(bytes: Uint8Array): FigMessage;\n}\n\ninterface FigMessage {\n  nodeChanges?: FigNodeChange[];\n  blobs?: Array<{ bytes?: Uint8Array }>;\n}\n\nfunction decodeCanvas(bytes: Uint8Array): FigMessage {\n  const prelude = asciiAt(bytes, 0, 8);\n  if (prelude !== FIG_MAGIC && prelude !== JAM_MAGIC) {\n    throw new Error(`unexpected prelude \"${prelude}\"`);\n  }\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n  // bytes 8..11: u32 version (unused). Chunks begin at offset 12.\n  let offset = 12;\n  const chunks: Uint8Array[] = [];\n  while (offset + 4 <= bytes.length && chunks.length < 2) {\n    const len = view.getUint32(offset, true);\n    offset += 4;\n    if (len === 0 || offset + len > bytes.length) break;\n    chunks.push(bytes.subarray(offset, offset + len));\n    offset += len;\n  }\n  const schemaChunk = chunks[0];\n  const messageChunk = chunks[1];\n  if (!schemaChunk || !messageChunk) {\n    throw new Error('expected schema + message chunks');\n  }\n  const schemaBytes = decompressChunk(schemaChunk);","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/nexu-io/open-design/blob/5be4028344c2eb4c667c5a97bda8f750c5597ef7/apps/daemon/src/figma/fig-decode.ts#L132-L168","documentation":"Plain Error thrown by decodeCanvas when the first 8 ASCII bytes of the .fig/.jam file do not match the magic prelude 'fig-kiwi' (FIG_MAGIC, a Figma design file) or 'fig-jam.' (JAM_MAGIC, a Figma Jam board). This is the file-format sentinel check at the entry of the binary container parser; anything that is not one of these two known Figma container formats is rejected before any chunk parsing.","triggerScenarios":"Passing a non-Figma file to the Figma importer: a PNG/SVG export from Figma (which are not .fig containers), a .fig file from an older/newer Figma format that changed the prelude, a corrupted/truncated file shorter than 8 bytes, or any unrelated binary masquerading with a .fig extension.","commonSituations":"User downloads a PNG from Figma and renames it .fig; user selects the wrong file in the import dialog; partial download where the first bytes are missing; a third-party tool producing files with a .fig extension that are not Figma containers; very new Figma format that introduced a third magic string not yet handled here.","solutions":["Confirm the file was exported from Figma via File > Save local copy (.fig) — not a PNG/SVG/PDF export.","Re-export the .fig file from Figma and re-import.","If the file is a Jam board, ensure it was saved as .jam from Figma Jam.","If a genuinely new Figma format (new magic), the importer needs an additional prelude case — file a bug rather than catching the error."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const FIG_MAGIC = 'fig-kiwi';\nconst JAM_MAGIC = 'fig-jam.';\nfunction isFigContainer(bytes: Uint8Array): boolean {\n  if (bytes.length < 8) return false;\n  const prelude = Array.from(bytes.slice(0, 8), (b) => String.fromCharCode(b)).join('');\n  return prelude === FIG_MAGIC || prelude === JAM_MAGIC;\n}\n// before importing\nif (!isFigContainer(fileBytes)) { reject('Not a valid .fig/.jam container'); }","typeGuard":null,"tryCatchPattern":"try {\n  await importFigma(fileBytes);\n} catch (err) {\n  if (err instanceof Error && /unexpected prelude/.test(err.message)) {\n    return respond(415, { error: 'Not a Figma .fig/.jam file. Use File > Save local copy in Figma.' });\n  }\n  throw err;\n}","preventionTips":["Export .fig via Figma File > Save local copy, not PNG/SVG/PDF export.","Do not rename PNG/SVG files to .fig.","Pre-check the 8-byte magic before invoking the importer."],"tags":["figma","import","file-format","binary","validation"],"backgroundTag":null,"analyzedSha":"5be4028344c2eb4c667c5a97bda8f750c5597ef7","analyzedAt":"2026-08-12T12:03:58.812Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}