{"record":{"id":"2ade96e160f2fb4a","repo":"moeru-ai/airi","slug":"cap-vite-cap-args-json-must-be-a-json-string-array","errorCode":null,"errorMessage":"CAP_VITE_CAP_ARGS_JSON must be a JSON string array.","messagePattern":"CAP_VITE_CAP_ARGS_JSON must be a JSON string array\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cap-vite/src/vite-wrapper-config.ts","lineNumber":15,"sourceCode":"import process from 'node:process'\n\nimport { defineConfig, loadConfigFromFile, mergeConfig } from 'vite'\n\nimport { capVitePlugin } from './vite-plugin'\n\nfunction parseCapArgs(): string[] {\n  const value = process.env.CAP_VITE_CAP_ARGS_JSON\n  if (!value) {\n    return []\n  }\n\n  const parsed = JSON.parse(value)\n  if (!Array.isArray(parsed) || parsed.some(arg => typeof arg !== 'string')) {\n    throw new Error('CAP_VITE_CAP_ARGS_JSON must be a JSON string array.')\n  }\n\n  return parsed\n}\n\nfunction parseConfigLoader(): 'bundle' | 'native' | 'runner' | undefined {\n  const value = process.env.CAP_VITE_CONFIG_LOADER\n  if (value === 'bundle' || value === 'native' || value === 'runner') {\n    return value\n  }\n\n  return undefined\n}\n\nexport default defineConfig(async (env) => {\n  const root = process.env.CAP_VITE_ROOT ?? process.cwd()\n  const baseConfigFile = process.env.CAP_VITE_BASE_CONFIG || undefined\n  const configLoader = parseConfigLoader()","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/moeru-ai/airi/blob/27111382b4a79a7e983289d6e983a06af185ed0f/packages/cap-vite/src/vite-wrapper-config.ts#L1-L33","documentation":"Thrown by parseCapArgs() inside vite-wrapper-config.ts when process.env.CAP_VITE_CAP_ARGS_JSON is set but does not JSON.parse into an array of strings. It guards the env-var contract that runCapVite establishes when it spawns the wrapper Vite process.","triggerScenarios":"CAP_VITE_CAP_ARGS_JSON is set to a JSON object, a JSON scalar, a non-JSON string, or an array containing non-string elements (numbers, null). JSON.parse itself throwing (malformed JSON) propagates a SyntaxError before this guard; this guard specifically catches the shape mismatch.","commonSituations":"Manually exporting the env var with a wrong shape in a script; a build tool that stringifies an object instead of an array; copy-paste of a CLI arg string without JSON encoding; the env var surviving from an experiment that put objects in it.","solutions":["Set CAP_VITE_CAP_ARGS_JSON to JSON.stringify(['ios']) style values only.","Let runCapVite() own the env var; avoid setting it by hand.","If scripting, validate with Array.isArray(parsed) && parsed.every(x => typeof x === 'string') before assigning the env."],"exampleFix":"// before\nprocess.env.CAP_VITE_CAP_ARGS_JSON = JSON.stringify({ platform: 'ios' })\n// after\nprocess.env.CAP_VITE_CAP_ARGS_JSON = JSON.stringify(['ios'])","handlingStrategy":"validation","validationCode":"function readCapArgsEnv(): string[] {\n  const raw = process.env.CAP_VITE_CAP_ARGS_JSON\n  if (!raw) return []\n  const parsed = JSON.parse(raw) as unknown\n  if (!Array.isArray(parsed) || parsed.some(a => typeof a !== 'string')) {\n    throw new Error('CAP_VITE_CAP_ARGS_JSON must be set to a JSON string array.')\n  }\n  return parsed\n}","typeGuard":"function isStringArray(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every(v => typeof v === 'string')\n}","tryCatchPattern":"try {\n  parseCapArgs()\n} catch (error) {\n  if (error instanceof Error && error.message.includes('JSON string array')) {\n    console.error('Fix CAP_VITE_CAP_ARGS_JSON; it must be a JSON-encoded string[].')\n  }\n  throw error\n}","preventionTips":["Use JSON.stringify(['ios', ...]) when setting the env var manually.","Let runCapVite own the env var; do not set it elsewhere.","Add a CI assertion that the env var, when present, parses to a string[]."],"tags":["capacitor","environment","json-parsing","vite-plugin"],"backgroundTag":null,"analyzedSha":"27111382b4a79a7e983289d6e983a06af185ed0f","analyzedAt":"2026-08-12T18:33:34.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}