usebruno/bruno · error · Error

Failed to parse the file – ensure it is valid JSON or YAML

Error message

Failed to parse the file – ensure it is valid JSON or YAML

What it means

Catch-all thrown by the async parse path in file-reader.js. It replaces any JSON.parse/jsyaml.load failure, or the explicit 'Document root must be an object' check, with a single user-facing message asking for valid JSON or YAML.

Source

Thrown at packages/bruno-app/src/utils/importers/file-reader.js:22

/**
 * Parse a File object as JSON or YAML and return the parsed object.
 * Throws with a user-friendly message on parse failure.
 */
export const parseFileAsJsonOrYaml = async (file) => {
  try {
    const text = await file.text();
    let parsed;
    if (file.name.toLowerCase().endsWith('.json')) {
      parsed = JSON.parse(text);
    } else {
      parsed = jsyaml.load(text);
    }
    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
      throw new Error('Document root must be an object');
    }
    return parsed;
  } catch {
    throw new Error('Failed to parse the file – ensure it is valid JSON or YAML');
  }
};

const readFile = (file) => {
  return new Promise((resolve, reject) => {
    const fileReader = new FileReader();
    fileReader.onload = (e) => {
      try {
        const parsed = JSON.parse(e.target.result);
        resolve({ fileName: file.name, content: parsed });
      } catch (err) {
        console.error(err);
        reject(new BrunoError(`Unable to parse JSON file: ${file.name}`));
      }
    };
    fileReader.onerror = (err) => reject(err);
    fileReader.readAsText(file);
  });

View on GitHub (pinned to 9bdd81c7bd)

Solutions

1. Open the file in an editor and run a JSON/YAML linter to find the syntax error.
2. If the root is an array, wrap it in an object or use an importer that accepts arrays.
3. Save the file as UTF-8 without BOM and retry.

Example fix

// before: file contains '[1, 2, 3]' (array root)
// after: file contains
{
  "info": { "type": "bruno-environment" },
  "environments": []
}

let parsed;
try {
  parsed = file.name.toLowerCase().endsWith('.json') ? JSON.parse(text) : jsyaml.load(text);
} catch (e) {
  throw new Error(`Syntax error: ${e.message}`);
}
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
  throw new Error('Root must be a JSON/YAML object');
}

function isObjectRoot(parsed) {
  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);
}

try {
  await parseFile(file);
} catch (err) {
  if (err.message.includes('valid JSON or YAML')) {
    // lint the file with a JSON/YAML validator before retrying
  }
  throw err;
}

When it happens

Trigger: A file whose text is not parseable JSON (when .json) or YAML (otherwise), OR a file whose parsed root is not an object (array, primitive, null). The try block swallows the original error and substitutes this generic message.

Common situations: Corrupted export, BOM/encoding issues, accidental plain-text content, a YAML file with tabs, or a JSON file whose top level is an array.

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

• Failed to read ${file.name}: ${err.message}
• Invalid environment: expected an object
• Invalid environment: missing or invalid variables array
• Invalid variable at index ${index}: expected an object
• Invalid variable at index ${index}: missing or invalid name

AI-assisted analysis of usebruno/bruno@9bdd81c7bd (2026-08-13). Data as JSON: /api/errors/ffa78e55bb4a4e37. Report an issue: GitHub.