langgenius/dify · error · BaseError

usage_invalid_flag

usage_invalid_flag

Error message

${JSON.stringify(args.id)} is not a valid app UUID

What it means

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.

Source

Thrown at cli/src/commands/describe/app/index.ts:42

  static override flags = {
    workspace: Flags.string({
      description: 'workspace id (overrides DIFY_WORKSPACE_ID and stored default)',
    }),
    'http-retry': httpRetryFlag,
    output: Flags.outputFormat({
      options: [OutputFormat.JSON, OutputFormat.YAML, OutputFormat.TEXT],
      default: '',
    }),
    refresh: Flags.boolean({
      description: 'bypass app-info cache and fetch fresh',
      default: false,
    }),
  }

  async run(argv: string[]) {
    const { args, flags } = this.parse(DescribeApp, argv)
    if (!isValidUuid(args.id))
      throw new BaseError({
        code: ErrorCode.UsageInvalidFlag,
        message: `${JSON.stringify(args.id)} is not a valid app UUID`,
      })
    const format = flags.output
    const ctx = await this.authedCtx({ retryFlag: flags['http-retry'], withCache: true, format })
    return formatted({
      format,
      data: await runDescribeApp(
        { appId: args.id, workspace: flags.workspace, format, refresh: flags.refresh },
        { active: ctx.active, http: ctx.http, host: ctx.host, io: ctx.io, cache: ctx.cache },
      ),
    })
  }

  override agentGuide(): string {
    return agentGuide
  }
}

View on GitHub (pinned to ef8544b173)

Solutions

1. Copy the app UUID from `difyctl list apps` (or the console URL `/apps/<uuid>`) and pass it verbatim.
2. Strip surrounding whitespace/quotes from the value before passing it.
3. If scripting, validate with the same regex before invoking the CLI to fail fast with a clearer message.

Example fix

// before
$ difyctl describe app my-chatbot
// after
$ difyctl describe app 9c4e1b2a-3f5d-4a6e-8b7c-1d2e3f4a5b6c

import { isValidUuid } from '@/workspace/resolver'
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
function assertAppUuid(id: string): void {
  if (!UUID_RE.test(id))
    throw new Error(`expected app UUID, got ${JSON.stringify(id)}`)
}

function isAppUuid(v: unknown): v is string {
  return typeof v === 'string' &&
    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v)
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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

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