{"record":{"id":"fb96e1547d04226c","repo":"langgenius/dify","slug":"usage-invalid-flag-fb96e1","errorCode":"usage_invalid_flag","errorMessage":"${JSON.stringify(args.id)} is not a valid app UUID","messagePattern":"(.+?) is not a valid app UUID","errorType":"error_code","errorClass":"BaseError","httpStatus":null,"severity":"error","filePath":"cli/src/commands/describe/app/index.ts","lineNumber":42,"sourceCode":"  static override flags = {\n    workspace: Flags.string({\n      description: 'workspace id (overrides DIFY_WORKSPACE_ID and stored default)',\n    }),\n    'http-retry': httpRetryFlag,\n    output: Flags.outputFormat({\n      options: [OutputFormat.JSON, OutputFormat.YAML, OutputFormat.TEXT],\n      default: '',\n    }),\n    refresh: Flags.boolean({\n      description: 'bypass app-info cache and fetch fresh',\n      default: false,\n    }),\n  }\n\n  async run(argv: string[]) {\n    const { args, flags } = this.parse(DescribeApp, argv)\n    if (!isValidUuid(args.id))\n      throw new BaseError({\n        code: ErrorCode.UsageInvalidFlag,\n        message: `${JSON.stringify(args.id)} is not a valid app UUID`,\n      })\n    const format = flags.output\n    const ctx = await this.authedCtx({ retryFlag: flags['http-retry'], withCache: true, format })\n    return formatted({\n      format,\n      data: await runDescribeApp(\n        { appId: args.id, workspace: flags.workspace, format, refresh: flags.refresh },\n        { active: ctx.active, http: ctx.http, host: ctx.host, io: ctx.io, cache: ctx.cache },\n      ),\n    })\n  }\n\n  override agentGuide(): string {\n    return agentGuide\n  }\n}","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/cli/src/commands/describe/app/index.ts#L24-L60","documentation":"Thrown by `difyctl describe app <id>` after parsing args, when the positional `id` fails the canonical UUID v4 regex (`/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i` in `isValidUuid`). It is a `usage_invalid_flag` BaseError that maps to exit code 2 (Usage). The check runs before any network call, so it fires offline.","triggerScenarios":"Running `difyctl describe app <id>` where `<id>` is not a hyphenated 36-char hex UUID: passing an app name/token, a URL, a short ID, or trailing whitespace. Also triggered by copy-paste errors (missing a segment, letter `O` instead of zero, uppercase handled fine but non-hex chars like `z` fail).","commonSituations":"User confuses the app's display name with its backend UUID; copies a slug from the console UI instead of the ID; passes the URL path segment; shell quoting mangles the value; the app ID came from an older Dify version using non-UUID identifiers.","solutions":["Copy the app UUID from `difyctl list apps` (or the console URL `/apps/<uuid>`) and pass it verbatim.","Strip surrounding whitespace/quotes from the value before passing it.","If scripting, validate with the same regex before invoking the CLI to fail fast with a clearer message."],"exampleFix":"// before\n$ difyctl describe app my-chatbot\n// after\n$ difyctl describe app 9c4e1b2a-3f5d-4a6e-8b7c-1d2e3f4a5b6c","handlingStrategy":"validation","validationCode":"import { isValidUuid } from '@/workspace/resolver'\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i\nfunction assertAppUuid(id: string): void {\n  if (!UUID_RE.test(id))\n    throw new Error(`expected app UUID, got ${JSON.stringify(id)}`)\n}","typeGuard":"function isAppUuid(v: unknown): v is string {\n  return typeof v === 'string' &&\n    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v)\n}","tryCatchPattern":null,"preventionTips":["Always copy app IDs from `difyctl list apps` or the console URL `/apps/<uuid>`.","In scripts, validate the UUID with the same regex before invoking the CLI.","Trim/quote shell-expanded values to avoid whitespace creeping into the arg."],"tags":["cli","validation","uuid","difyctl","typescript"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}