CherryHQ/cherry-studio · error · Error

Invalid args: must be an array

Error message

Invalid args: must be an array

What it means

Thrown by validateArgs() when the args field from an MCP package manifest is not an array. MCP package manifests define server.mcp_config.args as a string[], so a non-array value (object, string, number, null) is a schema violation. This is the first validation gate in validateArgs, checked before iterating individual elements.

Source

Thrown at src/main/ai/mcp/McpPackageService.ts:174

  // Check for null bytes
  if (trimmed.includes('\0')) {
    throw new Error('Invalid command: null byte detected')
  }

  return trimmed
}

/**
 * Validate command arguments to prevent injection attacks.
 * Rejects arguments containing path traversal sequences.
 *
 * @param args - The arguments array to validate
 * @returns The validated arguments array
 * @throws Error if any argument contains path traversal
 */
export function validateArgs(args: string[]): string[] {
  if (!Array.isArray(args)) {
    throw new Error('Invalid args: must be an array')
  }

  return args.map((arg, index) => {
    if (typeof arg !== 'string') {
      throw new Error(`Invalid args: argument at index ${index} must be a string`)
    }

    // Check for null bytes
    if (arg.includes('\0')) {
      throw new Error(`Invalid args: null byte detected in argument at index ${index}`)
    }

    // Check for path traversal in arguments that look like paths
    // Only validate if the arg contains path separators (indicating it's meant to be a path)
    if ((arg.includes('/') || arg.includes('\\')) && /(?:^|[/\\])\.\.(?:[/\\]|$)/.test(arg)) {
      throw new Error(`Invalid args: path traversal detected in argument at index ${index}`)
    }

View on GitHub (pinned to 726446b54c)

Solutions

1. Set the manifest's args to a JSON array of strings, e.g., ['--port', '3000'] instead of '--port 3000'.
2. If using platform_overrides, verify each override's args field is an array.
3. Validate the manifest JSON against the DXT/MCPB schema before installation.

Example fix

// before (manifest fragment)
"mcp_config": { "command": "node", "args": "--port 3000" }

// after
"mcp_config": { "command": "node", "args": ["--port", "3000"] }

// Validate args is an array before calling validateArgs
if (!Array.isArray(manifest.server.mcp_config.args)) {
  throw new Error('Manifest args field must be an array of strings')
}

function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every(item => typeof item === 'string')
}

When it happens

Trigger: Called from resolveMcpConfig at line 359 after variable substitution and mapping. Triggers when the manifest's args field is a non-array type — e.g., { args: '--port 3000' } (string instead of array), { args: null }, or the field is absent and defaulted to a non-array value.

Common situations: A manifest author wrote args as a single string instead of an array of strings; a platform_override replaced the args array with a non-array value; a schema migration or manual edit corrupted the args field type.

Related errors

• Invalid args: argument at index ${index} must be a string
• Invalid command: command must be a non-empty string
• Invalid command: command cannot be empty
• Invalid args: path traversal detected in argument at index $
• Invalid MCP package env: null byte detected in environment v

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/96e92ed6275fc0f3. Report an issue: GitHub.