langgenius/dify · error · ValidationError

Parameter '${key}' exceeds maximum length of ${MAX_STRING_LE

Error message

Parameter '${key}' exceeds maximum length of ${MAX_STRING_LENGTH} characters

What it means

Thrown by validateParams() in validation.ts:95 as a ValidationError. Unlike the named guards, validateParams runs in the HTTP layer (client.ts:490/494) over every query and record body param. Any string value (regardless of key) longer than 10000 characters is rejected. The key name is interpolated into the message.

Source

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

    return
  }
  if (value !== 'like' && value !== 'dislike') {
    throw new ValidationError("rating must be either 'like' or 'dislike'")
  }
}

export function validateParams(params: Record<string, unknown>): void {
  Object.entries(params).forEach(([key, value]) => {
    if (value === undefined || value === null) {
      return
    }

    // Only check max length for strings; empty strings are allowed for optional params
    // Required fields are validated at method level via ensureNonEmptyString
    if (typeof value === 'string') {
      if (value.length > MAX_STRING_LENGTH) {
        throw new ValidationError(
          `Parameter '${key}' exceeds maximum length of ${MAX_STRING_LENGTH} characters`,
        )
      }
    } else if (Array.isArray(value)) {
      if (value.length > MAX_LIST_LENGTH) {
        throw new ValidationError(
          `Parameter '${key}' exceeds maximum size of ${MAX_LIST_LENGTH} items`,
        )
      }
    } else if (isRecord(value)) {
      if (Object.keys(value).length > MAX_DICT_LENGTH) {
        throw new ValidationError(
          `Parameter '${key}' exceeds maximum size of ${MAX_DICT_LENGTH} items`,
        )
      }
    }

    if (key === 'user' && typeof value !== 'string') {
      throw new ValidationError(`Parameter '${key}' must be a string`)

View on GitHub (pinned to ef8544b173)

Solutions

  1. Move large content to the proper endpoint: use document upload + reference rather than inline text in a query.
  2. Truncate or summarize the field upstream to stay under 10000 chars.
  3. Inspect the error's interpolated `${key}` to identify which param is oversized and restructure that call.

Example fix

// before
await client.chat('fx', { query, user, inputs: { doc: fullText } }) // fullText > 10000

// after
const docId = await kb.createDocumentByText(ds, { name, text: fullText }, user)
await client.chat('fx', { query, user, inputs: { doc_id: docId } })
Defensive patterns

Strategy: validation

Validate before calling

const MAX_STRING_LENGTH = 10000
function clampStringParams(params: Record<string, unknown>) {
  for (const [k, v] of Object.entries(params)) {
    if (typeof v === 'string' && v.length > MAX_STRING_LENGTH) {
      throw new Error(`Parameter '${k}' too long; move to upload endpoint`)
    }
  }
}

Type guard

function isBoundedStringParams(params: Record<string, unknown>, max = 10000): boolean {
  return Object.values(params).every((v) => typeof v !== 'string' || v.length <= max)
}

Try / catch

try {
  await client.chat('fx', payload)
} catch (err) {
  if (err instanceof Error && /exceeds maximum length/.test(err.message)) {
    // extract the offending key, move to file upload, retry
  } else throw err
}

Prevention

When it happens

Trigger: Any request whose query or JSON body contains a string field > 10000 chars: chat messages, prompts, document text passed inline, or accidentally huge identifiers. Triggered from client.ts:489 (query) or client.ts:493 (body) for record-shaped data.

Common situations: Passing full document text as a query param instead of using the upload flow; large prompts in a chat request that exceed the cap; concatenated context windows.

Related errors

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