langgenius/dify · error · BaseError

UsageMissingArg

UsageMissingArg

Error message

a workspace id is required (no TTY)

What it means

Thrown by pickWorkspaceId when difyctl is asked to switch workspaces without an explicit id AND stderr is not a TTY. The interactive picker (selectFromList) requires a TTY on stderr; in non-interactive contexts (pipelines, CI, redirected stderr) it refuses to silently guess. The BaseError carries UsageMissingArg, which exitFor maps to exit code 2 (Usage). The hint text points at the exact invocation form.

Source

Thrown at cli/src/commands/use/workspace/use.ts:60

  const id = argId !== '' ? argId : await pickWorkspaceId(client, deps)

  const detail = await runWithSpinner({ io: deps.io, label: `Switching to ${id}` }, () =>
    client.switch(id),
  )

  const nextCtx = {
    ...deps.active.ctx,
    workspace: { id: detail.id, name: detail.name, role: detail.role },
  }
  deps.reg.upsert(deps.active.host, deps.active.email, nextCtx)
  await deps.reg.save()
  deps.io.out.write(`${cs.successIcon()} Switched to ${detail.name} (${detail.id})\n`)
  return deps.reg
}

async function pickWorkspaceId(client: WorkspacesClient, deps: UseWorkspaceDeps): Promise<string> {
  if (!deps.io.isErrTTY) {
    throw new BaseError({
      code: ErrorCode.UsageMissingArg,
      message: 'a workspace id is required (no TTY)',
      hint: "pass the id: 'difyctl use workspace <id>'",
    })
  }

  const list = await runWithSpinner({ io: deps.io, label: 'Loading workspaces' }, () =>
    client.list(),
  )
  const items = list.workspaces.map<Workspace>((w) => ({ id: w.id, name: w.name, role: w.role }))
  if (items.length === 0) {
    throw new BaseError({
      code: ErrorCode.AccessDenied,
      message: 'no workspaces available to switch to',
    })
  }

  const activeId = deps.active.ctx.workspace?.id

View on GitHub (pinned to ef8544b173)

Solutions

1. Pass the workspace id explicitly: `difyctl use workspace <id>` (ids come from `difyctl workspaces list`).
2. If you genuinely need the picker, allocate a TTY: `ssh -t`, `docker run -it`, or run in a real terminal without redirecting stderr.
3. In scripts, look up the id first via `difyctl workspaces list -o name` or `-o json` and pipe it into `use workspace`.
4. Avoid redirecting stderr (`2>` or `2>&1` to a file) when you want the interactive picker; keep stderr on the terminal.

Example fix

// before (fails in CI / piped stderr)
difyctl use workspace

// after — explicit id (script-friendly)
difyctl use workspace ws_abc123

// or — resolve id dynamically from a known name
ID=$(difyctl workspaces list -o json | jq -r '.workspaces[] | select(.name=="prod") | .id')
difyctl use workspace "$ID"

// before invoking runUseWorkspace, ensure an id is present in non-TTY contexts
import { runUseWorkspace, type UseWorkspaceOptions, type UseWorkspaceDeps } from '@/commands/use/workspace/use'
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'

function ensureWorkspaceIdOrTty(opts: UseWorkspaceOptions, deps: UseWorkspaceDeps): void {
  const hasId = (opts.workspaceId ?? '').trim() !== ''
  if (!hasId && !deps.io.isErrTTY) {
    throw new BaseError({
      code: ErrorCode.UsageMissingArg,
      message: 'pass --workspace-id when stderr is not a TTY',
      hint: 'difyctl use workspace <id>',
    })
  }
}

// usage
ensureWorkspaceIdOrTty(opts, deps)
const reg = await runUseWorkspace(opts, deps)

When it happens

Trigger: Invoking `difyctl use workspace` with no positional id while stderr is not a TTY. Concretely: `deps.io.isErrTTY === false` (process.stderr.isTTY falsy) at use.ts:59 AND opts.workspaceId is empty/whitespace (use.ts:41). Piping stderr (`difyctl use workspace 2>log`), running under CI runners, nohup, systemd, or in a Docker container without a pseudo-tty all make isErrTTY false.

Common situations: CI scripts that switch workspace before running a command; shell pipelines that redirect stderr for logging; running difyctl over ssh without tty allocation (`ssh host difyctl use workspace`); Docker `docker run` without -t; cron jobs; a user who forgot the id and expected a default.

Related errors

• UsageMissingArg
• UsageInvalidFlag
• AccessDenied
• unknown flag: --${name}
• unknown flag: -${char}

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