Stirling-Tools/Stirling-PDF · warning · Error

Invalid folder scanning config: expected JSON object

Error message

Invalid folder scanning config: expected JSON object

What it means

Thrown by parseFolderScanningConfig when the parsed value is not a plain object: it is null, an array, a primitive, or undefined. The folder-scanning format requires a top-level object containing a pipeline array.

Source

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

  candidate: string,
  toolRegistry: Partial<ToolRegistry>,
): boolean => Object.prototype.hasOwnProperty.call(toolRegistry, candidate);

/**
 * Parse a folder-scanning pipeline JSON into the native AutomationConfig
 * shape. Endpoint paths are reverse-mapped to frontend tool IDs via the
 * supplied registry; unmappable operations are kept verbatim and reported in
 * `unresolvedOperations`.
 */
export function parseFolderScanningConfig(
  raw: unknown,
  toolRegistry: Partial<ToolRegistry>,
): {
  automation: Omit<AutomationConfig, "id" | "createdAt" | "updatedAt">;
  unresolvedOperations: string[];
} {
  if (!raw || typeof raw !== "object") {
    throw new Error("Invalid folder scanning config: expected JSON object");
  }
  const obj = raw as Record<string, unknown>;
  const pipeline = obj.pipeline;
  if (!Array.isArray(pipeline)) {
    throw new Error("Invalid folder scanning config: missing 'pipeline' array");
  }

  const endpointMap = buildEndpointToToolIdMap(toolRegistry);
  const unresolved: string[] = [];

  const operations: AutomationOperation[] = pipeline.map(
    (step: unknown, index: number) => {
      if (!step || typeof step !== "object") {
        throw new Error(
          `Invalid folder scanning config: pipeline[${index}] is not an object`,
        );
      }
      const stepObj = step as Record<string, unknown>;

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Ensure the JSON is an object with a top-level pipeline array.
2. Validate the shape with a type guard before calling parseFolderScanningConfig.
3. Use detectAutomationFormat first to confirm the file is folder-scanning.

Example fix

// before
parseFolderScanningConfig(raw, toolRegistry);

// after
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
  throw new Error('Select a folder-scanning config object with a pipeline array.');
}
parseFolderScanningConfig(raw, toolRegistry);

if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
  throw new Error('Folder scanning config must be a JSON object.');
}

function isFolderScanningObject(raw: unknown): raw is Record<string, unknown> {
  return !!raw && typeof raw === 'object' && !Array.isArray(raw);
}

When it happens

Trigger: The imported JSON is an array of steps rather than the wrapper object, an empty/null file, or a bare primitive value.

Common situations: User selected a JSON that is an array of operations instead of the { pipeline: [...] } object; an empty file parsed to null; the wrong file was selected.

Related errors

• Invalid folder scanning config: missing 'pipeline' array
• Invalid folder scanning config: pipeline[${index}] is not an
• Invalid folder scanning config: pipeline[${index}].operation
• Invalid automation config: expected JSON object
• Invalid automation config: missing 'operations' array

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