{"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":"validation","errorClass":null,"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/27111382b4a79a7e983289d6e983a06af185ed0f/packages/cap-vite/src/index.ts#L139-L175","documentation":"Thrown by runCapVite() when capArgs[0] is not parseable by parseCapacitorPlatform(), which only accepts the literal strings 'ios' or 'android'. This is the CLI entry point of @proj-airi/cap-vite and is the first guard before forwarding args into Vite and the Capacitor run subprocess.","triggerScenarios":"Calling runCapVite(viteArgs, capArgs) with capArgs[0] missing, undefined, empty string, or any value other than 'ios'/'android' (e.g. 'web', 'electron', '--target'). Also triggered by argument-order mistakes where the platform is not placed first.","commonSituations":"Custom scripts that build capArgs dynamically and forget the platform token; CLI wrappers that pass '--target <id>' before the platform; typos like 'iOS'/'Android' with different casing; copying a Vite-only invocation into a cap-vite entry without adding the platform.","solutions":["Ensure the first element of the capArgs array is exactly 'ios' or 'android' (lowercase).","If the platform comes from user input, normalize and validate it before calling runCapVite using parseCapacitorPlatform().","Reorder args so the platform precedes any --target flag: runCapVite(viteArgs, ['ios', '--target', deviceId])."],"exampleFix":"// before\nawait runCapVite(viteArgs, ['--target', deviceId])\n// after\nawait runCapVite(viteArgs, ['ios', '--target', deviceId])","handlingStrategy":"validation","validationCode":"import { parseCapacitorPlatform } from '@proj-airi/cap-vite'\n\nfunction assertCapPlatform(capArgs: string[]): asserts capArgs is ['ios' | 'android', ...string[]] {\n  if (!parseCapacitorPlatform(capArgs[0])) {\n    throw new TypeError(`capArgs[0] must be 'ios' or 'android', got: ${String(capArgs[0])}`)\n  }\n}\n\nassertCapPlatform(capArgs)\nawait runCapVite(viteArgs, capArgs)","typeGuard":"import { parseCapacitorPlatform } from '@proj-airi/cap-vite'\n\nfunction isCapArgs(value: unknown): value is ['ios' | 'android', ...string[]] {\n  return Array.isArray(value)\n    && (value[0] === 'ios' || value[0] === 'android')\n    && value.every(v => typeof v === 'string')\n}","tryCatchPattern":"try {\n  await runCapVite(viteArgs, capArgs)\n} catch (error) {\n  if (error instanceof Error && error.message.includes('must be `ios` or `android`')) {\n    console.error('Usage: cap-vite <ios|android> [vite args]')\n    process.exit(2)\n  }\n  throw error\n}","preventionTips":["Always place the platform token as the first element of capArgs.","Validate platform at your CLI boundary before forwarding to runCapVite.","Normalize user input to lowercase before comparing."],"tags":["capacitor","argument-validation","cli"],"backgroundTag":null,"analyzedSha":"27111382b4a79a7e983289d6e983a06af185ed0f","analyzedAt":"2026-08-12T18:33:34.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}