langgenius/dify · error · BaseError

UsageInvalidFlag

UsageInvalidFlag

Error message

unknown host "${target}"; known hosts: ${hosts.join(', ')}

What it means

Thrown by `runUseHost` (use/host/use-host.ts:23) as `usage_invalid_flag` (exit 2) when the resolved `--domain` target is not among hosts registered in the local Registry. The message lists all known hosts. Fires after the empty-hosts guard (error: not logged in) but before setting the active host.

Source

Thrown at cli/src/commands/use/host/use-host.ts:23

import { colorEnabled, colorScheme } from '@/sys/io/color'
import { selectFromList } from '@/sys/io/select'

export type UseHostOptions = {
  readonly io: IOStreams
  readonly host: string | undefined
}

type HostChoice = { host: string; accounts: number; active: boolean }

export async function runUseHost(opts: UseHostOptions): Promise<void> {
  const cs = colorScheme(colorEnabled(opts.io.isErrTTY))
  const reg = await Registry.load()
  const hosts = Object.keys(reg.hosts)
  if (hosts.length === 0) throw notLoggedInError()

  const target = opts.host ?? (await pickHost(opts, reg, hosts))
  if (!hosts.includes(target)) {
    throw new BaseError({
      code: ErrorCode.UsageInvalidFlag,
      message: `unknown host "${target}"; known hosts: ${hosts.join(', ')}`,
    })
  }

  reg.setHost(target)
  await reg.save()
  opts.io.out.write(`${cs.successIcon()} Active host is now ${target}\n`)
}

async function pickHost(
  opts: UseHostOptions,
  reg: Registry,
  hosts: readonly string[],
): Promise<string> {
  if (!opts.io.isErrTTY) {
    throw new BaseError({
      code: ErrorCode.UsageMissingArg,

View on GitHub (pinned to ef8544b173)

Solutions

1. Pick a host from the message's `known hosts:` list.
2. If the intended host is missing, log in to add it: `difyctl auth login --host <host>`.
3. Check the registry to see configured hosts before switching.

Example fix

// before
$ difyctl use host wrong.dify.example
// after
$ difyctl use host api.dify.example

const reg = await Registry.load()
const hosts = Object.keys(reg.hosts)
function isKnownHost(host: string): boolean {
  return hosts.includes(host)
}

When it happens

Trigger: Running `difyctl use host wrong.dify.example` where that host was never added via login. `hosts.includes(target)` is false at line 22.

Common situations: Typo in the host/domain; using a host name from a different environment (staging vs prod); the host was removed from the registry; wrong scheme/port included.

Related errors

• UsageInvalidFlag
• UsageMissingArg
• NotLoggedIn
• UsageMissingArg
• usage_invalid_flag

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