{"record":{"id":"773eb2d9e1da996f","repo":"cypress-io/cypress","slug":"invalid-project-path-parameter-options-project","errorCode":null,"errorMessage":"Invalid project path parameter: ${options.project}","messagePattern":"Invalid project path parameter: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/lib/cypress.ts","lineNumber":25,"sourceCode":"import cliImport from './cli'\n\n  /**\n   * Opens Cypress GUI\n   * @see https://on.cypress.io/module-api#cypress-open\n   */\nexport function open (options: any = {}): any {\n  options = util.normalizeModuleOptions(options)\n\n  return openModule.start(options)\n}\n\n/**\n * Runs Cypress tests in the current project\n * @see https://on.cypress.io/module-api#cypress-run\n */\nexport async function run (options: any = {}): Promise<any> {\n  if (!runModule.isValidProject(options.project)) {\n    throw new Error(`Invalid project path parameter: ${options.project}`)\n  }\n\n  options = util.normalizeModuleOptions(options)\n  tmp.setGracefulCleanup()\n\n  const outputPath: string = tmp.fileSync().name\n\n  options.outputPath = outputPath\n\n  const failedTests = await runModule.start(options)\n  const output = await fs.readJson(outputPath, { throws: false })\n\n  if (!output) {\n    return {\n      status: 'failed',\n      failures: failedTests,\n      message: 'Could not find Cypress test run results',\n    }","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/cypress-io/cypress/blob/0d85fdc91230885bca0a91df278312800a48b727/cli/lib/cypress.ts#L7-L43","documentation":"Thrown by the programmatic Module API cypress.run() when options.project fails isValidProject(). That helper (cli/lib/exec/run.ts:17) rejects boolean values and the string literals 'true', 'false', and '' because cypress run, unlike cypress open, does not support global mode and needs a real project folder. The check exists so a stray `cypress run --project false` (valid for open) fails fast instead of launching a meaningless run.","triggerScenarios":"Calling cypress.run({ project: false }), cypress.run({ project: 'false' }), cypress.run({ project: 'true' }), or cypress.run({ project: '' }). Also when an unset shell variable is interpolated into a --project flag that is parsed and forwarded into the module API, or when options built for cypress.open() (where project:false means global mode) are reused for cypress.run().","commonSituations":"Reusing the same options object for both open and run; CI scripts that pass a conditional project flag that collapses to an empty string; tooling that sets project to a boolean flag instead of a path.","solutions":["Pass a concrete project path string, e.g. cypress.run({ project: process.cwd() }) or an absolute/relative directory path.","If you actually want global mode, use cypress.open({ project: false }) instead of cypress.run().","Sanitize the value before calling: ensure it is a non-empty string that is not 'true'/'false' before assigning it to options.project."],"exampleFix":"// before\nawait cypress.run({ project: useGlobal ? false : process.cwd() })\n\n// after\nawait cypress.run({ project: process.cwd() })","handlingStrategy":"validation","validationCode":"import isValidProject from './cli/lib/exec/run'\n\n// or inline the same checks the library uses:\nfunction safeProject(p: unknown): string {\n  if (typeof p === 'boolean' || p === '' || p === 'true' || p === 'false') {\n    throw new Error(`Refusing to call cypress.run() with invalid project: ${String(p)}`)\n  }\n  return p as string\n}\n\nconst project = safeProject(options.project)\nawait cypress.run({ ...options, project })","typeGuard":"function isValidProjectPath(v: unknown): v is string {\n  return typeof v === 'string' && v !== '' && v !== 'true' && v !== 'false'\n}","tryCatchPattern":"try {\n  await cypress.run({ project })\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Invalid project path parameter')) {\n    // surface a friendlier error pointing at how project was computed\n  }\n  throw e\n}","preventionTips":["Never reuse an options object built for cypress.open() (which allows project:false) directly with cypress.run().","Always set options.project to an absolute path such as process.cwd().","Assert the value is a non-empty string before calling cypress.run()."],"tags":["module-api","validation","project-path"],"backgroundTag":null,"analyzedSha":"0d85fdc91230885bca0a91df278312800a48b727","analyzedAt":"2026-08-12T16:24:28.056Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}