usebruno/bruno · error · Error

Invalid OpenAPI collection. Failed to resolve refs.

Error message

Invalid OpenAPI collection. Failed to resolve refs.

What it means

Error "Invalid OpenAPI collection. Failed to resolve refs." thrown in usebruno/bruno.

Source

Thrown at packages/bruno-converters/src/openapi/openapi-to-bruno.js:808

    // could use https://www.npmjs.com/package/json-pointer for better support
    return `res.body${pointer.replace('/', '.')}`;
  }
  return expression;
};

export const parseOpenApiCollection = (data, options = {}) => {
  const usedNames = new Set();
  const brunoCollection = {
    name: '',
    uid: uuid(),
    version: '1',
    items: [],
    environments: []
  };
  try {
    const collectionData = resolveRefs(data);
    if (!collectionData) {
      throw new Error('Invalid OpenAPI collection. Failed to resolve refs.');
      return;
    }

    // Currently parsing of openapi spec is "do your best", that is
    // allows "invalid" openapi spec

    brunoCollection.name = collectionData.info?.title?.trim() || 'Untitled Collection';

    let servers = collectionData.servers || [];

    // Create environments based on the servers. A server's name or description is free text
    // that becomes the environment's filename, so it needs the same normalization as an
    // operation name. It also needs a uniqueness guard: unlike requests, environments have
    // no deduplication, so two servers described alike resolve to one file and the later
    // one overwrites the earlier.
    const usedEnvironmentNames = new Set();
    servers.forEach((server, index) => {
      const serverLabel = server.name || server.description;

View on GitHub (pinned to 9bdd81c7bd)

Solutions

1. Bundle the OpenAPI spec so all $ref references resolve (e.g. with swagger-cli bundle).
2. Ensure referenced external files are present and paths are correct.

When it happens

Trigger: Thrown at packages/bruno-converters/src/openapi/openapi-to-bruno.js:808 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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