hoppscotch/hoppscotch · error · HoppCLIError

MALFORMED_COLLECTION

MALFORMED_COLLECTION

Error message

MALFORMED_COLLECTION

What it means

Thrown by `getValidRequests` (recursively, into nested folders) when zod fails to validate `collection.requests` against `z.array(entityReference(HoppRESTRequest))`. The schema validates each request object inside a folder; the first folder whose `requests` array contains an invalid request aborts with this code, attaching the collection file path and a generic hint.

Source

Thrown at packages/hoppscotch-cli/src/utils/mutators.ts:25

import { error } from "../types/errors";
import { FormDataEntry } from "../types/request";
import { isHoppErrnoException } from "./checks";
import { getResourceContents } from "./getters";

const getValidRequests = (
  collections: HoppCollection[],
  collectionFilePath: string
) => {
  return collections.map((collection) => {
    // Validate requests using zod schema
    const requestSchemaParsedResult = z
      .array(entityReference(HoppRESTRequest))
      .safeParse(collection.requests);

    // Handle validation errors
    if (!requestSchemaParsedResult.success) {
      throw error({
        code: "MALFORMED_COLLECTION",
        path: collectionFilePath,
        data: "Please check the collection data.",
      });
    }

    // Recursively validate requests in nested folders
    if (collection.folders.length > 0) {
      collection.folders = getValidRequests(
        collection.folders,
        collectionFilePath
      );
    }

    // Return validated collection
    return {
      ...collection,
      requests: requestSchemaParsedResult.data,
    };

View on GitHub (pinned to 1acb8a3a75)

Solutions

1. Re-export the collection from a current Hoppscotch client rather than hand-editing it.
2. Open the collection JSON and inspect each request object — every request needs `v`, `method`, `endpoint`, `name`, `headers`, `params`, `auth`, `body`, `preRequestScript`, `testScript`, `requestVariables`.
3. If only one folder is affected, isolate it: run `hopp test` on a trimmed collection to identify the offending request.
4. Upgrade the CLI to a version whose `HoppRESTRequest` schema matches the client that produced the collection.

Example fix

// before: request object missing required `body` field
{ "v": 1, "name": "x", "method": "GET", "endpoint": "/u", "auth": {"authActive": false, "authType": "none"}, "headers": [], "params": [] }

// after: include body
{ "v": 1, "name": "x", "method": "GET", "endpoint": "/u", "auth": {"authActive": false, "authType": "none"}, "headers": [], "params": [], "body": {"contentType": null, "body": ""} }

import { z } from 'zod';
import { entityReference } from 'verzod';
import { HoppRESTRequest } from '@hoppscotch/data';

const schema = z.array(entityReference(HoppRESTRequest));
function validateRequests(requests: unknown[], label: string) {
  const r = schema.safeParse(requests);
  if (!r.success) console.error(`Folder ${label}:`, r.error.issues);
  return r.success;
}

const hasValidRequests = (c: unknown): boolean =>
  schema.safeParse((c as any)?.requests).success;

try { return getValidRequests(collections, path); }
catch (e) {
  if (isHoppCLIError(e) && e.code === 'MALFORMED_COLLECTION') {
    // quarantine the bad collection, continue with the rest
    return collections.filter(c => schema.safeParse(c.requests).success);
  } throw e;
}

When it happens

Trigger: A request object is missing required fields (`method`, `endpoint`, `auth`, `headers`, `params`, `body`); a request was hand-edited and its `v` (version) field is invalid; an old collection exported by a much older Hoppscotch client whose request schema no longer satisfies `HoppRESTRequest`.

Common situations: Manually editing exported collection JSON; collection exported from an outdated self-hosted Hoppscotch; partial/corrupt export that truncated a request object.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• INVALID_ID
• auth/invalid_auth_header
• INVALID_OPENAPI_SPEC
• Invalid JSON
• payload is not an object

AI-assisted analysis of hoppscotch/hoppscotch@1acb8a3a75 (2026-08-12). Data as JSON: /api/errors/1b7a72ed65c98de5. Report an issue: GitHub.