langgenius/dify · error · KnowledgeCreationError

Knowledge creation failed during create

Error message

Knowledge creation failed during create

What it means

Wrapped KnowledgeCreationError thrown when the createKnowledgeSpace API call (consoleClient.knowledgeFs.createKnowledgeSpace) rejects. It captures stage='create' and the original error so callers can distinguish a creation failure from a later policy failure. Because no knowledge space was created, no createdKnowledge is attached.

Source

Thrown at web/features/new-rag/create-knowledge-workflow.ts:64

  const status = responseStatus(error)
  return status === 400 || status === 401 || status === 403 || status === 422
}

export async function createKnowledge(
  values: CreateKnowledgeValues,
): Promise<KnowledgeSpaceCreationResponse> {
  let created = values.existingKnowledge
  if (!created) {
    try {
      created = await consoleClient.knowledgeFs.createKnowledgeSpace({
        body: {
          description: values.description || undefined,
          idempotencyKey: values.idempotencyKey,
          name: values.name,
        },
      })
    } catch (error) {
      throw new KnowledgeCreationError('create', error)
    }
  }
  values.onCreated(created)

  try {
    if (values.visibility === 'all_members') {
      const policy = await consoleClient.knowledgeFs.getKnowledgeSpacesByIdAccessPolicy({
        params: { id: created.id },
      })
      if (policy.visibility !== values.visibility) {
        await consoleClient.knowledgeFs.patchKnowledgeSpacesByIdAccessPolicy({
          body: {
            expectedRevision: policy.revision,
            partialMemberSubjectIds: [],
            visibility: values.visibility,
          },
          params: { id: created.id },
        })

View on GitHub (pinned to ef8544b173)

Solutions

1. Inspect error.originalError.status to classify: 409/duplicate -> prompt for a new name; 401/403 -> re-auth; 5xx/network -> retry.
2. Reuse the same idempotencyKey when retrying with an identical payload to avoid duplicate spaces.
3. If isDefinitiveCreationRejection(error.originalError) is true, do not retry automatically.
4. Validate name length against NAME_MAX_LENGTH (160) and description against DESCRIPTION_MAX_LENGTH (2000) before calling.

Example fix

// before
catch (error) {
  throw new KnowledgeCreationError('create', error)
}

// after - caller-side classification
try {
  return await createKnowledge(values)
} catch (e) {
  if (e instanceof KnowledgeCreationError && e.stage === 'create') {
    if (isDefinitiveCreationRejection(e.originalError)) showFormError(e.originalError)
    else scheduleRetry(values.idempotencyKey)
  }
  throw e
}

// Validate inputs before calling createKnowledge
function validateKnowledgeInput(values: CreateKnowledgeValues): string | null {
  if (!values.name?.trim()) return 'Name is required'
  if (values.name.length > NAME_MAX_LENGTH) return `Name exceeds ${NAME_MAX_LENGTH} chars`
  if (values.description.length > DESCRIPTION_MAX_LENGTH) return `Description exceeds ${DESCRIPTION_MAX_LENGTH} chars`
  if (!values.idempotencyKey) return 'Idempotency key is required'
  return null
}

function isKnowledgeCreationError(e: unknown): e is KnowledgeCreationError {
  return e instanceof KnowledgeCreationError
}

try {
  return await createKnowledge(values)
} catch (e) {
  if (e instanceof KnowledgeCreationError && e.stage === 'create') {
    if (isDefinitiveCreationRejection(e.originalError)) throw new ValidationError(e.originalError)
    // transient - safe to retry with same idempotencyKey
    throw e
  }
  throw e
}

When it happens

Trigger: Fires when values.existingKnowledge is undefined and the POST to create the knowledge space fails for any reason: 400 validation (duplicate name, over-length), 401/403 auth, 422 schema, 5xx server, or network error.

Common situations: Duplicate knowledge space name already exists, the idempotencyKey was reused with different payload, the user's session expired, or the KnowledgeFS backend is unreachable. The companion isDefinitiveCreationRejection helper identifies 400/401/403/422 as non-retryable.

Related errors

• Knowledge creation failed during policy
• Unknown
• deployFailed
• Missing required deployment binding.
• Missing required deployment environment variable.

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