langgenius/dify · error · BaseError

UsageInvalidFlag

UsageInvalidFlag

Error message

--inputs and --inputs-file are mutually exclusive

What it means

Thrown by `resolveInputs` (input-flags.ts:15) — shared by `run app` and `resume app` — when both `--inputs` (inline JSON) and `--inputs-file` (JSON file path) are supplied. The CLI treats them as mutually exclusive input sources; passing both is a `usage_invalid_flag` (exit 2) before any parsing.

Source

Thrown at cli/src/commands/run/app/input-flags.ts:15

import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'

// Output formats that render the run/resume result as plain text rather than JSON/YAML.
export const TEXT_FORMATS = new Set(['', 'text'])

// Shared by `run app` and `resume app`: --inputs (inline JSON) / --inputs-file (JSON file) /
// direct inputs are mutually exclusive ways to supply the run's variable map.
export async function resolveInputs(
  inputsJson: string | undefined,
  inputsFile: string | undefined,
  directInputs: Readonly<Record<string, unknown>> | undefined,
): Promise<Record<string, unknown>> {
  if (inputsJson !== undefined && inputsFile !== undefined)
    throw new BaseError({
      code: ErrorCode.UsageInvalidFlag,
      message: '--inputs and --inputs-file are mutually exclusive',
    })
  if (inputsJson !== undefined) {
    let parsed: unknown
    try {
      parsed = JSON.parse(inputsJson)
    } catch {
      throw new BaseError({
        code: ErrorCode.UsageInvalidFlag,
        message: '--inputs must be valid JSON',
      })
    }
    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
      throw new BaseError({
        code: ErrorCode.UsageInvalidFlag,
        message: '--inputs must be a JSON object',
      })

View on GitHub (pinned to ef8544b173)

Solutions

1. Keep only one source: inline `--inputs` for quick runs, `--inputs-file` for large/structured payloads.
2. Audit wrapper scripts to ensure exactly one of the two flags is emitted.
3. Use direct inputs via the API/SDK instead of flags if both are needed in different code paths.

Example fix

// before
$ difyctl run app <uuid> --inputs '{"q":1}' --inputs-file ./in.json
// after
$ difyctl run app <uuid> --inputs-file ./in.json

function hasSingleInputSource(
  inputsJson: unknown,
  inputsFile: unknown,
): boolean {
  return (inputsJson !== undefined ? 1 : 0) + (inputsFile !== undefined ? 1 : 0) <= 1
}

When it happens

Trigger: Invoking `difyctl run app <uuid> --inputs '{"q":1}' --inputs-file ./in.json` simultaneously. The check at line 14 fires when neither argument is `undefined`.

Common situations: User iteratively adds `--inputs-file` and forgets to remove a stale `--inputs`; a wrapper script appends both; copy-paste from two examples combines them.

Related errors

• UsageInvalidFlag
• usage_invalid_flag
• UsageInvalidFlag
• usage_invalid_flag
• --action required: form has multiple user actions

AI-assisted analysis of langgenius/dify@ef8544b173 (2026-08-12). Data as JSON: /api/errors/044b7aa80932700e. Report an issue: GitHub.