{"record":{"id":"c027b8539ef7b158","repo":"Stirling-Tools/Stirling-PDF","slug":"unrecognized-json-shape-expected-an-automate-conf","errorCode":null,"errorMessage":"Unrecognized JSON shape. Expected an Automate config (operations[]) or a Folder Scanning config (pipeline[]).","messagePattern":"Unrecognized JSON shape\\. Expected an Automate config \\(operations\\[\\]\\) or a Folder Scanning config \\(pipeline\\[\\]\\)\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"frontend/editor/src/core/utils/automationConverter.ts","lineNumber":423,"sourceCode":"        expectedFormat === \"automate\"\n          ? \"Automate JSON (operations array)\"\n          : \"Folder Scanning JSON (pipeline array)\"\n      } but file looks like ${\n        detected === \"automate\" ? \"Automate JSON\" : \"Folder Scanning JSON\"\n      }.`,\n    );\n  }\n\n  if (format === \"automate\") {\n    const result = parseAutomationConfigJson(raw, toolRegistry);\n    return { format: \"automate\", ...result };\n  }\n  if (format === \"folderScanning\") {\n    const result = parseFolderScanningConfig(raw, toolRegistry);\n    return { format: \"folderScanning\", ...result };\n  }\n\n  throw new Error(\n    \"Unrecognized JSON shape. Expected an Automate config (operations[]) or a Folder Scanning config (pipeline[]).\",\n  );\n}\n","sourceCodeStart":405,"sourceCodeEnd":427,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/utils/automationConverter.ts#L405-L427","documentation":"Thrown by parseAutomationFile when a parsed JSON object matches neither the Automate format (a top-level 'operations' array) nor the Folder Scanning format (a top-level 'pipeline' array). The function first runs detectAutomationFormat, which returns 'unknown' for any object lacking exactly one of those arrays, and since 'unknown' is not a dispatchable format the final fallthrough throws. It is a structural-validation error: the JSON parsed successfully but its shape is unrecognizable.","triggerScenarios":"Calling parseAutomationFile(fileText, registry) or parseAutomationFile(fileText, registry, undefined) with a JSON string that is a valid object but has no 'operations' and no 'pipeline' key (e.g. {\"steps\": []}), has both keys at once (detected as 'unknown' per detectAutomationFormat), or where either key is present but not an array. Also reached when expectedFormat is omitted, detected is 'unknown', so format stays 'unknown' and neither if-branch fires.","commonSituations":"User imports the wrong file type into the automation importer (e.g. a settings JSON, a pipeline watch-config, or arbitrary export). The JSON has both 'operations' and 'pipeline' arrays. A schema/key was renamed in a newer export format (e.g. 'operations' changed to 'steps') but the importer was not updated. The file is a partial/corrupt export missing the top-level array.","solutions":["Open the JSON file and confirm it has exactly one top-level array key: 'operations' for Automate config or 'pipeline' for Folder Scanning config.","If the file uses a different key name (e.g. 'steps'), rename it to 'operations' or 'pipeline' to match the expected schema.","If the file legitimately has neither shape, it is the wrong file — re-export the automation from the correct source.","Pass an explicit expectedFormat ('automate' | 'folderScanning') so the mismatch error fires earlier with a clearer message instead of this generic fallthrough."],"exampleFix":"// before — file contains { \"steps\": [ ... ] }\n// after  — rename the key to match the Automate schema\n{\n  \"operations\": [ ... ]\n}","handlingStrategy":"validation","validationCode":"import { detectAutomationFormat } from '@app/utils/automationConverter';\n\nfunction isValidAutomationJson(text: string): boolean {\n  let raw: unknown;\n  try { raw = JSON.parse(text); } catch { return false; }\n  return detectAutomationFormat(raw) !== 'unknown';\n}\n\n// before calling parseAutomationFile:\nif (!isValidAutomationJson(fileText)) {\n  throw new Error('File must contain an operations[] or pipeline[] array.');\n}","typeGuard":"function isAutomateShape(raw: unknown): raw is { operations: unknown[] } {\n  return !!raw && typeof raw === 'object' &&\n    Array.isArray((raw as any).operations) &&\n    !Array.isArray((raw as any).pipeline);\n}\n\nfunction isFolderScanningShape(raw: unknown): raw is { pipeline: unknown[] } {\n  return !!raw && typeof raw === 'object' &&\n    Array.isArray((raw as any).pipeline) &&\n    !Array.isArray((raw as any).operations);\n}","tryCatchPattern":"try {\n  const parsed = parseAutomationFile(fileText, toolRegistry);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Unrecognized JSON shape')) {\n    showUser('This file is not a valid Automate or Folder Scanning config.');\n  } else { throw e; }\n}","preventionTips":["Run detectAutomationFormat on imported JSON before dispatching to the parser.","Validate file shape in the import UI and reject unknown formats with a clear message.","Pass an explicit expectedFormat when the import context knows which type is expected.","Add a JSON-schema check in CI for committed automation example files."],"tags":["automation","json-parsing","validation","config"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}