{"record":{"id":"bfe972d9760ee46c","repo":"moeru-ai/airi","slug":"the-first-cap-run-argument-must-be-ios-or-and","errorCode":null,"errorMessage":"The first `cap run` argument must be `ios` or `android`.","messagePattern":"The first `cap run` argument must be `ios` or `android`\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cap-vite/src/index.ts","lineNumber":157,"sourceCode":"    index += parsedArg.consumedArgs\n  }\n\n  return {\n    baseConfigFile,\n    configLoader,\n    projectRoot,\n    viteArgs: forwardedViteArgs,\n    wrapperConfigFile: resolveWrapperConfigFile(),\n  }\n}\n\nexport async function runCapVite(\n  viteArgs: string[],\n  capArgs: string[],\n  options: RunCapViteOptions = {},\n): Promise<Output> {\n  if (!parseCapacitorPlatform(capArgs[0])) {\n    throw new Error('The first `cap run` argument must be `ios` or `android`.')\n  }\n\n  const cwd = resolve(options.cwd ?? process.cwd())\n  const prepared = prepareCapViteLaunch(viteArgs, cwd)\n\n  return await x('vite', ['--config', prepared.wrapperConfigFile, ...prepared.viteArgs], {\n    throwOnError: false,\n    nodeOptions: {\n      cwd,\n      env: {\n        CAP_VITE_BASE_CONFIG: prepared.baseConfigFile ?? '',\n        CAP_VITE_CAP_ARGS_JSON: JSON.stringify(capArgs),\n        CAP_VITE_CONFIG_LOADER: prepared.configLoader ?? '',\n        CAP_VITE_ROOT: prepared.projectRoot,\n      },\n      stdio: 'inherit',\n    },\n  })","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/moeru-ai/airi/blob/677329427f32468c74b17f3ec47eeca4e05bec65/packages/cap-vite/src/index.ts#L139-L175","documentation":"runCapVite, the programmatic entry, validates capArgs[0] with parseCapacitorPlatform before doing anything: only 'ios' or 'android' may be the first `cap run` argument. This mirrors the CLI check and fails fast before spawning Vite.","triggerScenarios":"Calling runCapVite(viteArgs, []) with an empty capArgs array, or with a flag first: runCapVite([], ['--target', 'emulator-5554']) — capArgs[0] is not a platform.","commonSituations":"Wrapping runCapVite in tooling that forwards user flags verbatim and forgets to prepend the platform; empty array from a defaulted parameter.","solutions":["Prepend the platform: runCapVite([], ['android', '--target', 'emulator-5554'])","Validate with the same rule before calling: capArgs[0] === 'ios' || capArgs[0] === 'android'","For raw CLI input, run it through parseCapViteCliArgs first, which produces correctly ordered capArgs"],"exampleFix":"// before\nawait runCapVite([], ['--target', 'emulator-5554']) // Error: The first `cap run` argument must be `ios` or `android`.\n\n// after\nawait runCapVite([], ['android', '--target', 'emulator-5554'])","handlingStrategy":"validation","validationCode":"const platform = capArgs[0]\nif (platform !== 'ios' && platform !== 'android')\n  throw new Error(`capArgs must start with ios|android, got: ${platform}`)\nawait runCapVite(viteArgs, capArgs)","typeGuard":"function isCapacitorPlatform(v: string | undefined): v is 'ios' | 'android' {\n  return v === 'ios' || v === 'android'\n}","tryCatchPattern":null,"preventionTips":["Build capArgs by prepending the platform to user flags, never forwarding flags alone","Reuse parseCapViteCliArgs output instead of hand-assembling arrays"],"tags":["capacitor","vite","api-misuse","arguments"],"backgroundTag":"invalid-cli-argument","analyzedSha":"677329427f32468c74b17f3ec47eeca4e05bec65","analyzedAt":"2026-08-18T17:29:58.153Z","contentChangedAt":"2026-08-18T17:29:58.153Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}