langgenius/dify · error · ValidationError

metadata must be one of all, only, without

Error message

metadata must be one of all, only, without

What it means

Thrown by getDocument() in knowledge-base.ts:295 as a ValidationError when options.metadata is set to a value outside the allowed set {'all','only','without'}. The metadata query param controls whether the response includes document metadata, only metadata, or excludes it.

Source

Thrown at sdks/nodejs-client/src/client/knowledge-base.ts:295

        page: options?.page,
        limit: options?.limit,
        keyword: options?.keyword ?? undefined,
        status: options?.status ?? undefined,
      },
    })
  }

  async getDocument(
    datasetId: string,
    documentId: string,
    options?: DocumentGetOptions,
  ): Promise<DifyResponse<KnowledgeBaseResponse>> {
    ensureNonEmptyString(datasetId, 'datasetId')
    ensureNonEmptyString(documentId, 'documentId')
    if (options?.metadata) {
      const allowed = new Set(['all', 'only', 'without'])
      if (!allowed.has(options.metadata)) {
        throw new ValidationError('metadata must be one of all, only, without')
      }
    }
    return this.http.request({
      method: 'GET',
      path: `/datasets/${datasetId}/documents/${documentId}`,
      query: {
        metadata: options?.metadata ?? undefined,
      },
    })
  }

  async deleteDocument(
    datasetId: string,
    documentId: string,
  ): Promise<DifyResponse<KnowledgeBaseResponse>> {
    ensureNonEmptyString(datasetId, 'datasetId')
    ensureNonEmptyString(documentId, 'documentId')
    return this.http.request({

View on GitHub (pinned to ef8544b173)

Solutions

1. Use one of the three literal lowercase values: kb.getDocument(ds, doc, { metadata: 'all' }).
2. If the option is optional, omit it entirely rather than passing '' or null.
3. Constrain the upstream type to a union: metadata?: 'all' | 'only' | 'without' so the compiler rejects typos.

Example fix

// before
await kb.getDocument(ds, doc, { metadata: 'Only' })

// after
await kb.getDocument(ds, doc, { metadata: 'only' })

const METADATA_OPTIONS = new Set(['all', 'only', 'without'] as const)
function assertMetadataOption(value: unknown) {
  if (value !== undefined && !METADATA_OPTIONS.has(value as 'all')) {
    throw new Error(`metadata must be one of all, only, without`)
  }
}

function isMetadataOption(value: unknown): value is 'all' | 'only' | 'without' {
  return value === 'all' || value === 'only' || value === 'without'
}

try {
  await kb.getDocument(ds, doc, { metadata })
} catch (err) {
  if (err instanceof Error && /metadata must be one of/.test(err.message)) {
    // fall back to no metadata option
    await kb.getDocument(ds, doc)
  } else throw err
}

When it happens

Trigger: Calling kb.getDocument(datasetId, documentId, { metadata: 'full' }) or any typo like 'Only' (capitalized), 'with', 'none'. The Set membership check at knowledge-base.ts:294 fails.

Common situations: Case mismatch ('All' vs 'all'); assuming additional values like 'full' or 'none'; passing the value from an unvalidated UI dropdown; copy-pasting from API docs that list a different vocabulary.

Related errors

• unsupported argument value
• ${context} requires FormData
• ${name} must be a non-empty array
• rating must be either 'like' or 'dislike'
• Invalid type: {req_data.type}

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