Stirling-Tools/Stirling-PDF · error · Error

Unrecognized JSON shape. Expected an Automate config (operat

Error message

Unrecognized JSON shape. Expected an Automate config (operations[]) or a Folder Scanning config (pipeline[]).

What it means

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.

Source

Thrown at frontend/editor/src/core/utils/automationConverter.ts:423

        expectedFormat === "automate"
          ? "Automate JSON (operations array)"
          : "Folder Scanning JSON (pipeline array)"
      } but file looks like ${
        detected === "automate" ? "Automate JSON" : "Folder Scanning JSON"
      }.`,
    );
  }

  if (format === "automate") {
    const result = parseAutomationConfigJson(raw, toolRegistry);
    return { format: "automate", ...result };
  }
  if (format === "folderScanning") {
    const result = parseFolderScanningConfig(raw, toolRegistry);
    return { format: "folderScanning", ...result };
  }

  throw new Error(
    "Unrecognized JSON shape. Expected an Automate config (operations[]) or a Folder Scanning config (pipeline[]).",
  );
}

View on GitHub (pinned to 9ef20dcab8)

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.

Example fix

// before — file contains { "steps": [ ... ] }
// after  — rename the key to match the Automate schema
{
  "operations": [ ... ]
}

Defensive patterns

Strategy: validation

Validate before calling

import { detectAutomationFormat } from '@app/utils/automationConverter';

function isValidAutomationJson(text: string): boolean {
  let raw: unknown;
  try { raw = JSON.parse(text); } catch { return false; }
  return detectAutomationFormat(raw) !== 'unknown';
}

// before calling parseAutomationFile:
if (!isValidAutomationJson(fileText)) {
  throw new Error('File must contain an operations[] or pipeline[] array.');
}

Type guard

function isAutomateShape(raw: unknown): raw is { operations: unknown[] } {
  return !!raw && typeof raw === 'object' &&
    Array.isArray((raw as any).operations) &&
    !Array.isArray((raw as any).pipeline);
}

function isFolderScanningShape(raw: unknown): raw is { pipeline: unknown[] } {
  return !!raw && typeof raw === 'object' &&
    Array.isArray((raw as any).pipeline) &&
    !Array.isArray((raw as any).operations);
}

Try / catch

try {
  const parsed = parseAutomationFile(fileText, toolRegistry);
} catch (e) {
  if (e instanceof Error && e.message.includes('Unrecognized JSON shape')) {
    showUser('This file is not a valid Automate or Folder Scanning config.');
  } else { throw e; }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/c027b8539ef7b158. Report an issue: GitHub.