{"record":{"id":"ed51d8737519a79b","repo":"langgenius/dify","slug":"usageinvalidflag","errorCode":"UsageInvalidFlag","errorMessage":"--file value must start with @ (local file) or http(s):// (remote URL)","messagePattern":"--file value must start with @ \\(local file\\) or http\\(s\\):// \\(remote URL\\)","errorType":"error_code","errorClass":"BaseError","httpStatus":null,"severity":"error","filePath":"cli/src/commands/run/app/file-flags.ts","lineNumber":31,"sourceCode":"      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\n  throw new BaseError({\n    code: ErrorCode.UsageInvalidFlag,\n    message: '--file value must start with @ (local file) or http(s):// (remote URL)',\n  })\n}\n\nconst IMAGE_EXTS = new Set(['jpg', 'jpeg', 'png', 'webp', 'gif', 'svg'])\nconst AUDIO_EXTS = new Set(['mp3', 'm4a', 'wav', 'amr', 'mpga'])\nconst VIDEO_EXTS = new Set(['mp4', 'mov', 'mpeg', 'webm'])\n// Matches graphon/file/constants.py DOCUMENT_EXTENSIONS (Unstructured ETL config)\nconst DOCUMENT_EXTS = new Set([\n  'txt',\n  'markdown',\n  'md',\n  'mdx',\n  'pdf',\n  'html',\n  'htm',\n  'xlsx',","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/cli/src/commands/run/app/file-flags.ts#L13-L49","documentation":"Thrown by `parseFileFlag` (file-flags.ts:31) when the value after `key=` is neither a local path (prefix `@`) nor an HTTP(S) URL (prefix `http://`/`https://`). The parser only supports those two transfer methods; anything else (bare relative path, `ftp://`, `file://`, `s3://`) is rejected as `usage_invalid_flag` (exit 2). Note: the throw uses `ErrorCode.UsageInvalidFlag` (the SOURCE shows `code=UsageInvalidFlag` referencing the same constant).","triggerScenarios":"Passing `--file doc=./report.pdf` (forgot `@`), `--file doc=ftp://host/x.pdf`, `--file doc=file:///abs/path`, or `--file doc=data:...`. The value does not start with `@`, `http://`, or `https://`.","commonSituations":"User omits the `@` sigil thinking the path is enough; uses a `file://` URI; pastes a cloud-storage URL with an unsupported scheme; relative path without the `@` prefix.","solutions":["Prefix local paths with `@`: `--file doc=@./report.pdf`.","Use full `https://` URLs for remote files (e.g. presigned S3/GCS links).","Download non-http(s) sources to a local file first, then upload with `@`."],"exampleFix":"// before\n$ difyctl run app <uuid> --file doc=./report.pdf\n// after\n$ difyctl run app <uuid> --file doc=@./report.pdf","handlingStrategy":"validation","validationCode":"function isValidFileValue(raw: string): boolean {\n  const eq = raw.indexOf('=')\n  if (eq < 0) return false\n  const value = raw.slice(eq + 1)\n  return value.startsWith('@') ||\n    value.startsWith('http://') ||\n    value.startsWith('https://')\n}","typeGuard":"type ParsedFileFlag =\n  | { varname: string; kind: 'local'; path: string }\n  | { varname: string; kind: 'remote'; url: string }\n\nfunction isParsableFileFlag(raw: string): boolean {\n  const eq = raw.indexOf('=')\n  if (eq <= 0) return false\n  const v = raw.slice(eq + 1)\n  return v.startsWith('@') || v.startsWith('http://') || v.startsWith('https://')\n}","tryCatchPattern":null,"preventionTips":["Prefix local paths with `@`; use full `https://` for remote URLs.","Download non-http(s) sources (ftp://, s3://) to a local file first.","Avoid `file://` URIs — the parser does not accept them."],"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"}