TypeError: a.map is not a function in buildBaseFullConfig when running Cypress programmatically via cypress.run()

[dipyomoy]

Current behavior

When running Cypress programmatically using the Module API (cypress.run()), Cypress fails during initialization with the following error:

TypeError: a.map is not a function

The error occurs before any tests execute, inside Cypress's internal buildBaseFullConfig logic (line ~2592:56060).

What works

• Cypress CLI execution (npx cypress run)
• Shell / bash scripts that invoke the Cypress CLI

What fails

• Programmatic execution via require('cypress').run()

CLI execution completes successfully using the same configuration and test files.

---

Desired behavior

Programmatic execution via cypress.run() should behave the same as CLI execution and complete successfully without throwing a TypeError during configuration processing.

---

Test code to reproduce

Project structure

project-root/
├── cypress.config.ts
├── cypress/
│   ├── e2e/
│   │   └── test.cy.ts
│   └── fixtures/
│       └── environment.json
└── run-cypress.js

---

cypress.config.ts

import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'https://example.com',
    specPattern: 'cypress/e2e/**/*.cy.ts',
    async setupNodeEvents(on, config) {
      return config;
    },
  },
});

---

cypress/e2e/test.cy.ts

// Top-level JSON import triggers the issue when using cypress.run()
import testData from '../../fixtures/environment.json';

describe('Test', () => {
  it('should work', () => {
    cy.visit('/');
  });
});

Note: The imported JSON does not need to be used; the presence of the import alone is sufficient to trigger the issue.

---

cypress/fixtures/environment.json

{
  "production": {
    "testUrls": []
  }
}

---

run-cypress.js

const cypress = require('cypress');

cypress
  .run({
    spec: ['cypress/e2e/test.cy.ts'],
    headless: true,
    browser: 'electron',
    env: {
      CYPRESS_NETWORK_THROTTLE: '4g-50mbps',
      CYPRESS_TEST_ENV: 'production',
    },
  })
  .then(results => console.log(results))
  .catch(err => console.error(err));

---

Run command

node run-cypress.js

Expected: Tests run successfully
Actual: Error occurs during initialization

---

Environment

• Cypress: 13.15.x, 13.16.1, 13.17.0, 14.x, 15.x
• Node.js: 20.x LTS (also reproducible on 22.x)
• TypeScript: 5.9.3 (with resolveJsonModule: true, module: "commonjs")
• OS: macOS (Darwin 24.6.0)
• Package Manager: yarn

---

Debug Logs

TypeError: a.map is not a function
    at D.buildBaseFullConfig (<embedded>:2592:56060)
    at async D.getFullInitialConfig (<embedded>:2592:56822)
    at async D.setupNodeEvents (<embedded>:2592:50907)

The error occurs during Cypress initialization, inside buildBaseFullConfig, before any test executes.
CLI execution works; programmatic execution fails.

---

Other

Additional context / analysis

• The error occurs during Cypress initialization, before any spec code executes
• The issue only appears when using the Module API (cypress.run)
• CLI execution follows a different internal initialization path and does not trigger the error
• The presence of a top-level JSON import in a spec file changes how Cypress resolves spec metadata
• During programmatic execution, this results in an internal value reaching buildBaseFullConfig that is not an array, leading to a .map() call on a non-array value

---

Attempted solutions

1. Cypress Module API (cypress.run())

   • Passed config as a JavaScript object
   • Used spec as both string and array formats
   • Avoided CLI argument parsing
     Result: Error persists

2. Config simplification

   • Minimal cypress.config.ts
   • Removed all dynamic or conditional config
     Result: Error persists

3. Config structure variations

   • Tried configFile override
     Result: Error persists

4. Version testing

   • Cypress 13.x → 15.x
     Result: Error persists across versions

5. Environment isolation

   • Validated JSON fixture contents before execution
     Result: Error persists

6. Import attributes syntax

   • Tested import testData from '../../fixtures/environment.json' with { type: 'json' };
   • TypeScript 5.9.3 supports import attributes (TypeScript 5.0+)
   • Result: Error persists (same behavior as without with syntax)
   • Note: The with { type: 'json' } syntax is required for pure Node.js ESM (Node.js ESM docs), but TypeScript with resolveJsonModule: true handles JSON imports differently (TypeScript docs - note: does not mention with syntax). Since CLI execution works with the current syntax, this suggests the issue is in Cypress's internal processing rather than the import syntax itself.

---

Impact

• Blocks multi-run orchestration and CI/CD workflows that rely on programmatic execution
• Prevents Node.js-based Cypress runners from functioning
• Current workaround is invoking the Cypress CLI via shell scripts, which limits automation flexibility

---

Summary

Programmatic Cypress execution fails during internal config normalization when a spec contains a top-level JSON import.
CLI execution is unaffected, indicating a discrepancy between the CLI and Module API initialization paths.

Priority: High
Date: January 2026

[MikeMcC399]

@dipyomoy

See https://nodejs.org/docs/latest-v20.x/api/esm.html#json-modules

The with { type: 'json' } syntax is mandatory;

[dipyomoy]

Thanks for the suggestion. The with { type: 'json' } syntax is required for pure Node.js ESM (https://nodejs.org/docs/latest-v20.x/api/esm.html#import-attributes).

This project uses TypeScript with resolveJsonModule: true and CommonJS output, where JSON imports are handled differently. The current import syntax works when running Cypress via the CLI, but the failure occurs only when using cypress.run().

This suggests the issue is in Cypress’s internal buildBaseFullConfig processing rather than the import syntax itself.

I’ll still try the with { type: 'json' } approach, but the root cause appears to be in Cypress’s programmatic execution path.

[MikeMcC399]

@dipyomoy

I would certainly suggest applying the Node.js documentation's syntax first, even if you think that should not be necessary. If the change works, then this would be your fastest way to a resolution.

I see that the TypeScript documentation https://www.typescriptlang.org/tsconfig/#resolveJsonModule does not mention using the type syntax.

[dipyomoy]

Thanks for the suggestion, @MikeMcC399 . I really appreciate you taking a look at this.

Testing Results:

• Tested import testData from '../../fixtures/environment.json' with { type: 'json' };
• TypeScript 5.9.3 supports import attributes (TypeScript 5.0+)
• Error persists (same behavior as without with syntax)

TypeScript Documentation Analysis:

• Checked the TypeScript resolveJsonModule docs
• Interestingly, it doesn't mention the with syntax at all
• With resolveJsonModule: true and module: "commonjs", TypeScript transpiles JSON imports to require() calls at compile-time
• The with syntax is for pure Node.js ESM runtime, but in our TypeScript/Cypress setup, TypeScript handles it differently

Key Observations:

• CLI execution (npx cypress run) works perfectly with the current syntax (without with)
• Same code, same syntax, but different execution paths
• This suggests the issue is in Cypress's internal processing rather than the import syntax itself
• The error happens in buildBaseFullConfig during programmatic execution, not during import resolution

Next Steps:

• Happy to test any other approaches or provide more debugging info if that would help.

[jennifer-shehane]

@dipyomoy Hey, I copied as much as you described in your issue and created a repo here. Running this repo does not reproduce the issue - can you find any differences with your project that I may be missing? https://github.com/jennifer-shehane/test-json-import-issue

[dipyomoy]

@jennifer-shehane Thanks for creating the test repo. I found several critical differences that explain why the issue isn't reproducing. The main trigger is runtime file modification immediately before cypress.run(), combined with specific configuration settings.

Critical Differences

1. Runtime File Modification (Most Important)

Your test repo uses a static JSON file. In our setup, we modify the JSON file at runtime, immediately before calling cypress.run(), which triggers the race condition.

2. Specific Browser/Throttle Configuration

The error reproduces more reliably with:

• Browser: chrome (not electron)
• Network throttle: 5g (via environment variables)
• Multi-browser/multi-throttle flags enabled

3. Experimental Memory Management

Our cypress.config.ts includes:

experimentalMemoryManagement: true,
numTestsKeptInMemory: 1,

4. Multiple Imports in Test File

Our test file has multiple top-level imports (not just the JSON):

import '../support/types';
import '../support/commands';
import environmentConfig from '../fixtures/environment.json';

Complete Standalone Reproduction Script

I've created a complete standalone reproduction script (reproduce-cypress-json-issue.js) that creates everything from scratch and reproduces the error consistently. This script:

• Creates a temporary Cypress project programmatically
• Sets up all files (config, support files, test files)
• Modifies the JSON file at runtime before each cypress.run()
• Includes batch processing to increase reproduction likelihood
• Has comprehensive error detection

To use the standalone script:

1. Save the script below as reproduce-cypress-json-issue.js in your test repo
2. Run it with the specific environment variables that trigger the error:

CYPRESS_MULTI_BROWSER=true \
CYPRESS_BROWSERS=chrome \
CYPRESS_MULTI_THROTTLE=true \
CYPRESS_THROTTLES=5g \
node reproduce-cypress-json-issue.js

The script will:

• Create a temporary Cypress project in cypress-json-repro/ directory
• Set up all necessary files
• Run Cypress with the exact configuration that triggers the error
• Report if the error was reproduced

I've verified this script reproduces the error consistently (5/5 runs) with the exact configuration above.

Complete script (reproduce-cypress-json-issue.js):

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const cypress = require('cypress');

const ROOT = path.join(__dirname, 'cypress-json-repro');
const CYPRESS = path.join(ROOT, 'cypress');
const FIXTURES = path.join(CYPRESS, 'fixtures');
const E2E = path.join(CYPRESS, 'e2e');
const SUPPORT = path.join(CYPRESS, 'support');

const ENV_JSON = path.join(FIXTURES, 'environment.json');
const BACKUP_ENV = path.join(FIXTURES, 'environment.json.backup');

fs.rmSync(ROOT, { recursive: true, force: true });
fs.mkdirSync(FIXTURES, { recursive: true });
fs.mkdirSync(E2E, { recursive: true });
fs.mkdirSync(SUPPORT, { recursive: true });

const initialEnvData = {
  production: {
    testUrls: [
      {
        documentName: 'test-1',
        url: 'https://example.com/test1',
        timeout: 1800000,
      },
      {
        documentName: 'test-2',
        url: 'https://example.com/test2',
        timeout: 1800000,
      },
      {
        documentName: 'test-3',
        url: 'https://example.com/test3',
        timeout: 1800000,
      },
      {
        documentName: 'test-4',
        url: 'https://example.com/test4',
        timeout: 1800000,
      },
      {
        documentName: 'test-5',
        url: 'https://example.com/test5',
        timeout: 1800000,
      },
    ],
  },
};

fs.writeFileSync(ENV_JSON, JSON.stringify(initialEnvData, null, 2));
fs.copyFileSync(ENV_JSON, BACKUP_ENV);

fs.writeFileSync(
  path.join(SUPPORT, 'types.ts'),
  `export type TestUrl = {
  documentName: string;
  url: string;
  timeout: number;
};
`
);

fs.writeFileSync(
  path.join(SUPPORT, 'commands.ts'),
  `declare global {
  namespace Cypress {
    interface Chainable {
    }
  }
}
export {};
`
);

fs.writeFileSync(
  path.join(E2E, 'test.cy.ts'),
  `/// <reference types="cypress" />
import '../support/types';
import '../support/commands';
import environmentConfig from '../fixtures/environment.json';

describe('a.map repro - matches production code', () => {
  it('uses json import', () => {
    expect(environmentConfig.production.testUrls).to.be.an('array');
    expect(environmentConfig.production.testUrls.length).to.be.greaterThan(0);
  });
});
`
);

fs.writeFileSync(path.join(SUPPORT, 'e2e.ts'), `\n`);

fs.writeFileSync(
  path.join(ROOT, 'cypress.config.ts'),
  `
import { defineConfig } from 'cypress';

export default defineConfig({
  experimentalMemoryManagement: true,
  numTestsKeptInMemory: 1,
  e2e: {
    specPattern: 'cypress/e2e/**/*.cy.ts',
    async setupNodeEvents(on, config) {
      on('task', {
        testTask: () => {
          return null;
        },
      });
      return config;
    },
  },
});
`
);

fs.writeFileSync(
  path.join(ROOT, 'tsconfig.json'),
  JSON.stringify(
    {
      compilerOptions: {
        module: 'commonjs',
        target: 'ES2020',
        resolveJsonModule: true,
        esModuleInterop: true,
      },
      include: ['cypress/**/*.ts'],
    },
    null,
    2
  )
);

function restoreBackup() {
  try {
    if (fs.existsSync(BACKUP_ENV)) {
      fs.copyFileSync(BACKUP_ENV, ENV_JSON);
      return true;
    }
    return false;
  } catch (error) {
    console.error(`Error restoring backup: ${error.message}`);
    return false;
  }
}

async function createBatchEnvironment(batchUrls) {
  try {
    if (!Array.isArray(batchUrls) || batchUrls.length === 0) {
      throw new Error('Batch URLs must be a non-empty array');
    }
    const sourceFile = fs.existsSync(BACKUP_ENV) ? BACKUP_ENV : ENV_JSON;
    const data = JSON.parse(fs.readFileSync(sourceFile, 'utf8'));
    const env = process.env.CYPRESS_TEST_ENV || process.env.TEST_ENV || 'production';
    data[env] = data[env] || {};
    data[env].testUrls = batchUrls;
    fs.writeFileSync(ENV_JSON, JSON.stringify(data, null, 2));

    const fd = fs.openSync(ENV_JSON, 'r+');
    fs.fsyncSync(fd);
    fs.closeSync(fd);

    await new Promise(resolve => setTimeout(resolve, 200));
    
    const verifyData = JSON.parse(fs.readFileSync(ENV_JSON, 'utf8'));
    if (JSON.stringify(verifyData) !== JSON.stringify(data)) {
      throw new Error('File content verification failed - file may be corrupted');
    }
    
    JSON.parse(fs.readFileSync(ENV_JSON, 'utf8'));

    return true;
  } catch (error) {
    console.error(`Error creating batch environment: ${error.message}`);
    return false;
  }
}

async function runBatch(batchNum, batchUrls) {
  console.log(`BATCH ${batchNum} - Processing ${batchUrls.length} URLs`);

  if (!restoreBackup()) {
    console.error('Failed to restore backup');
    return { success: false, error: 'Backup restore failed' };
  }

  if (!(await createBatchEnvironment(batchUrls))) {
    console.error('Failed to create batch environment');
    return { success: false, error: 'Batch environment creation failed' };
  }

  const originalCwd = process.cwd();
  process.chdir(ROOT);

  const cypressConfig = {
    config: {
      e2e: {
        specPattern: 'cypress/e2e/**/*.cy.ts',
      },
    },
    spec: ['cypress/e2e/test.cy.ts'],
    headless: process.env.CYPRESS_HEADLESS !== 'false',
    browser: process.env.CYPRESS_BROWSER || (process.env.CYPRESS_MULTI_BROWSER === 'true' && process.env.CYPRESS_BROWSERS ? process.env.CYPRESS_BROWSERS.split(',')[0] : 'chrome'),
    env: {
      ...process.env,
      CYPRESS_TEST_ENV: process.env.CYPRESS_TEST_ENV || 'production',
      CYPRESS_NETWORK_THROTTLE: process.env.CYPRESS_NETWORK_THROTTLE || (process.env.CYPRESS_MULTI_THROTTLE === 'true' && process.env.CYPRESS_THROTTLES ? process.env.CYPRESS_THROTTLES.split(',')[0] : '5g'),
      CYPRESS_MULTI_THROTTLE: process.env.CYPRESS_MULTI_THROTTLE || 'true',
      CYPRESS_THROTTLES: process.env.CYPRESS_THROTTLES || '5g',
      CYPRESS_PERFORMANCE_CLEANUP_DONE: 'false',
      CYPRESS_BATCH_SIZE: batchUrls.length.toString(),
    },
  };
  
  if (cypressConfig.browser && (!/^[a-z0-9-]+$/.test(cypressConfig.browser) || cypressConfig.browser.length > 20)) {
    console.error('Invalid CYPRESS_BROWSER value');
    return { success: false, error: 'Invalid browser name' };
  }

  try {
    const results = await cypress.run(cypressConfig);
    
    const errorMsg = results.message || '';
    const failures = results.failures || [];
    const failureMessages = failures.map(f => f.message || JSON.stringify(f)).join(' ');
    
    const hasError = 
      errorMsg.includes('a.map is not a function') ||
      (errorMsg.includes('TypeError') && errorMsg.includes('a.map')) ||
      failureMessages.includes('a.map is not a function') ||
      (failureMessages.includes('TypeError') && failureMessages.includes('a.map'));

    if (hasError) {
      console.error('REPRODUCED: a.map is not a function');
      console.error('Error details:', errorMsg || failureMessages);
      process.chdir(originalCwd);
      return { success: false, error: 'a.map error', reproduced: true };
    }

    if (results.status === 'finished' || (results.status === undefined && results.totalPassed !== undefined)) {
      if (results.totalFailed === 0) {
        process.chdir(originalCwd);
        return { success: true, result: results };
      } else {
        console.error(`Cypress run completed with ${results.totalFailed} failure(s)`);
        process.chdir(originalCwd);
        return { success: false, error: `Tests failed: ${results.totalFailed} failure(s)` };
      }
    } else {
      if (results.totalPassed !== undefined && results.totalFailed === 0) {
        process.chdir(originalCwd);
        return { success: true, result: results };
      }
      console.error(`Cypress run status: ${results.status || 'undefined'}`);
      process.chdir(originalCwd);
      return { success: false, error: `Unexpected status: ${results.status || 'undefined'}` };
    }
  } catch (error) {
    console.error(`Cypress run failed: ${error.message}`);
    const fullError = error.stack || error.message || JSON.stringify(error);
    if (fullError.includes('a.map is not a function') || 
        (fullError.includes('TypeError') && fullError.includes('a.map')) ||
        fullError.includes('failures.map is not a function')) {
      console.error('REPRODUCED: a.map is not a function');
      console.error('The error occurred during Cypress initialization, corrupting the result object.');
      process.chdir(originalCwd);
      return { success: false, error: error.message, reproduced: true };
    }
    process.chdir(originalCwd);
    return { success: false, error: error.message };
  }
}

(async () => {
  const allUrls = initialEnvData.production.testUrls;
  const batchSize = 2;

  let reproduced = false;
  let batchNum = 1;

  for (let i = 0; i < allUrls.length; i += batchSize) {
    const batchUrls = allUrls.slice(i, i + batchSize);
    const result = await runBatch(batchNum, batchUrls);

    if (result.reproduced) {
      reproduced = true;
      console.error(`Error reproduced in batch ${batchNum}`);
      break;
    }

    if (!result.success) {
      console.error(`Batch ${batchNum} failed: ${result.error}`);
    } else {
      console.log(`Batch ${batchNum} completed successfully`);
    }

    batchNum++;
  }

  if (!reproduced) {
    console.log('Error was not reproduced in this run.');
    console.log('This error is intermittent. Try running the script multiple times.');
    console.log('To reproduce: CYPRESS_MULTI_BROWSER=true CYPRESS_BROWSERS=chrome CYPRESS_MULTI_THROTTLE=true CYPRESS_THROTTLES=5g node reproduce-cypress-json-issue.js');
  } else {
    console.log('SUCCESS: The error was reproduced!');
  }
})();

---

Why This Triggers the Error

1. Timing is critical: File modification → fsyncSync() → delay → cypress.run() (all in sequence)
2. Cypress processes imports during initialization: When Cypress reads the spec file, it resolves the JSON import
3. File state mismatch: If the file was just modified, Cypress's internal buildBaseFullConfig may receive an inconsistent or partially processed value where it expects an array
4. Module API vs CLI: CLI execution works because it uses a different initialization path that doesn't have this race condition

Additional Notes

• Error is fatal (tests may still complete, but error appears during initialization)
• Even with fs.fsyncSync() and delays, the error persists
• The error corrupts the result object, causing failures.map is not a function as a error

The runtime file modification combined with the specific browser/throttle settings appears to be the key trigger. The standalone script should reproduce the error.

[dipyomoy]

@jennifer-shehane Hope this helps clarify the issue and makes it easier to reproduce 🙂 🙂
Looking forward to hearing some good news from you soon 🤞🚀 🙂 🙂