{"record":{"id":"13d9bb682bb1f04e","repo":"langgenius/dify","slug":"usage-invalid-flag-13d9bb","errorCode":"usage_invalid_flag","errorMessage":"--file must be key=@path or key=https://url","messagePattern":"--file must be key=@path or key=https://url","errorType":"error_code","errorClass":"BaseError","httpStatus":null,"severity":"error","filePath":"cli/src/commands/run/app/file-flags.ts","lineNumber":12,"sourceCode":"import { basename } from 'node:path'\nimport { BaseError } from '@/errors/base'\nimport { ErrorCode } from '@/errors/codes'\n\nexport type ParsedFileFlag =\n  | { varname: string; kind: 'local'; path: string }\n  | { varname: string; kind: 'remote'; url: string }\n\nexport function parseFileFlag(raw: string): ParsedFileFlag {\n  const eqIdx = raw.indexOf('=')\n  if (eqIdx === -1)\n    throw new BaseError({\n      code: ErrorCode.UsageInvalidFlag,\n      message: '--file must be key=@path or key=https://url',\n    })\n\n  const varname = raw.slice(0, eqIdx)\n  const value = raw.slice(eqIdx + 1)\n\n  if (varname === '')\n    throw new BaseError({\n      code: ErrorCode.UsageInvalidFlag,\n      message: '--file varname must not be empty',\n    })\n\n  if (value.startsWith('@')) return { varname, kind: 'local', path: value.slice(1) }\n\n  if (value.startsWith('http://') || value.startsWith('https://'))\n    return { varname, kind: 'remote', url: value }\n","sourceCodeStart":1,"sourceCodeEnd":30,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/cli/src/commands/run/app/file-flags.ts#L1-L30","documentation":"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.","triggerScenarios":"Running `difyctl run app ... --file ./photo.png` or `--file https://example.com/x.pdf` (no `key=` prefix). Any `--file` token where `indexOf('=') === -1`.","commonSituations":"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.","solutions":["Use the `key=@path` form for local files: `--file avatar=@./photo.png`.","Use the `key=https://url` form for remote files: `--file doc=https://example.com/x.pdf`.","Ensure the key matches the workflow input variable name expected by the app."],"exampleFix":"// before\n$ difyctl run app <uuid> --file ./photo.png\n// after\n$ difyctl run app <uuid> --file avatar=@./photo.png","handlingStrategy":"validation","validationCode":"function isValidFileFlag(raw: string): boolean {\n  return raw.includes('=') // parseFileFlag requires at least one '='\n}","typeGuard":"function isFileFlagShape(raw: string): boolean {\n  const eq = raw.indexOf('=')\n  return eq > 0 // varname non-empty, has '='\n}","tryCatchPattern":null,"preventionTips":["Always format file flags as `key=@path` or `key=https://url`.","Match the key to the workflow input variable name.","When generating flags programmatically, assert the presence of `=` before emitting."],"tags":["cli","file-upload","flag-parsing","difyctl","typescript"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}