langgenius/dify · error · ValidationError

${name} exceeds maximum length of ${MAX_STRING_LENGTH} chara

Error message

${name} exceeds maximum length of ${MAX_STRING_LENGTH} characters

What it means

Thrown by ensureNonEmptyString() in validation.ts:13 as a ValidationError when a required string exceeds 10000 characters (MAX_STRING_LENGTH). The cap is a defensive guard against accidentally passing oversized payloads (e.g. document text, prompts) into identifier fields. It applies to every field validated through ensureNonEmptyString — user, datasetId, fileId, name, etc.

Source

Thrown at sdks/nodejs-client/src/client/validation.ts:13

import { ValidationError } from '../errors/dify-error'
import { isRecord } from '../internal/type-guards'

const MAX_STRING_LENGTH = 10000
const MAX_LIST_LENGTH = 1000
const MAX_DICT_LENGTH = 100

export function ensureNonEmptyString(value: unknown, name: string): asserts value is string {
  if (typeof value !== 'string' || value.trim().length === 0) {
    throw new ValidationError(`${name} must be a non-empty string`)
  }
  if (value.length > MAX_STRING_LENGTH) {
    throw new ValidationError(`${name} exceeds maximum length of ${MAX_STRING_LENGTH} characters`)
  }
}

/**
 * Validates optional string fields that must be non-empty when provided.
 * Use this for fields like `name` that are optional but should not be empty strings.
 *
 * For filter parameters that accept empty strings (e.g., `keyword: ""`),
 * use `validateParams` which allows empty strings for optional params.
 */
export function ensureOptionalString(value: unknown, name: string): void {
  if (value === undefined || value === null) {
    return
  }
  if (typeof value !== 'string' || value.trim().length === 0) {
    throw new ValidationError(`${name} must be a non-empty string when set`)
  }
  if (value.length > MAX_STRING_LENGTH) {

View on GitHub (pinned to ef8544b173)

Solutions

Verify you are passing the short identifier, not the content: pass the file id from a prior upload, not the file bytes.
Trim or hash the value if you genuinely need a long user identifier — the SDK caps at 10000 chars by design.
Inspect the call stack to confirm which `${name}` triggered the error and route the long payload to the correct API (e.g. createDocumentByText for body content).

Example fix

// before
await client.filePreview(base64AudioBlob, user) // wrong arg

// after
await client.filePreview(uploadedFileId, user)

Defensive patterns

Strategy: validation

Validate before calling

function requireShortId(value: unknown, name: string, max = 256): string {
  if (typeof value !== 'string' || value.trim().length === 0) throw new Error(`${name} required`)
  if (value.length > max) throw new Error(`${name} looks like content, not an id`)
  return value
}

Type guard

function isShortId(value: unknown, max = 256): value is string {
  return typeof value === 'string' && value.trim().length > 0 && value.length <= max
}

Try / catch

try {
  await client.filePreview(fileId, user)
} catch (err) {
  if (err instanceof Error && /exceeds maximum length/.test(err.message)) {
    // prompt caller to upload first, then preview by id
  } else throw err
}

Prevention

Distinguish identifier fields from content fields in your types.
Run a sanity check: any id longer than ~256 chars is suspicious.
Never serialize large blobs into id slots.

When it happens

Trigger: Passing a long string into a required-string slot: client.filePreview(hugeBlob, user) where the first arg is a base64 blob rather than a short file id; createDataset({ name: veryLongTitle }); user identifier sourced from a JWT or large token.

Common situations: Confusing a content field with an id field; concatenating user metadata into the user field; passing a serialized JSON blob where a short id was expected; copy-pasting a prompt into the wrong argument.

Related errors

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