langgenius/dify · error · BaseError

usage_invalid_flag

usage_invalid_flag

Error message

--file must be key=@path or key=https://url

What it means

Thrown by `parseFileFlag` in cli/src/commands/run/app/file-flags.ts:12 when a `--file` argument contains no `=` separator. The parser splits on the first `=` into varname/value; absence means the user passed a bare path or URL with no key binding. It is a `usage_invalid_flag` BaseError → exit code 2.

Source

Thrown at cli/src/commands/run/app/file-flags.ts:12

import { basename } from 'node:path'
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'

export type ParsedFileFlag =
  | { varname: string; kind: 'local'; path: string }
  | { varname: string; kind: 'remote'; url: string }

export function parseFileFlag(raw: string): ParsedFileFlag {
  const eqIdx = raw.indexOf('=')
  if (eqIdx === -1)
    throw new BaseError({
      code: ErrorCode.UsageInvalidFlag,
      message: '--file must be key=@path or key=https://url',
    })

  const varname = raw.slice(0, eqIdx)
  const value = raw.slice(eqIdx + 1)

  if (varname === '')
    throw new BaseError({
      code: ErrorCode.UsageInvalidFlag,
      message: '--file varname must not be empty',
    })

  if (value.startsWith('@')) return { varname, kind: 'local', path: value.slice(1) }

  if (value.startsWith('http://') || value.startsWith('https://'))
    return { varname, kind: 'remote', url: value }

View on GitHub (pinned to ef8544b173)

Solutions

1. Use the `key=@path` form for local files: `--file avatar=@./photo.png`.
2. Use the `key=https://url` form for remote files: `--file doc=https://example.com/x.pdf`.
3. Ensure the key matches the workflow input variable name expected by the app.

Example fix

// before
$ difyctl run app <uuid> --file ./photo.png
// after
$ difyctl run app <uuid> --file avatar=@./photo.png

function isValidFileFlag(raw: string): boolean {
  return raw.includes('=') // parseFileFlag requires at least one '='
}

function isFileFlagShape(raw: string): boolean {
  const eq = raw.indexOf('=')
  return eq > 0 // varname non-empty, has '='
}

When it happens

Trigger: Running `difyctl run app ... --file ./photo.png` or `--file https://example.com/x.pdf` (no `key=` prefix). Any `--file` token where `indexOf('=') === -1`.

Common situations: User assumes `--file` takes a plain path like many CLIs; copy-paste from docs that omitted the `key=` prefix; migrating from an older CLI syntax that was positional.

Related errors

• UsageInvalidFlag
• Unknown
• UsageInvalidFlag
• UsageInvalidFlag
• usage_invalid_flag

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