weaviate/weaviate · error

parse knn specific settings

Error message

parse knn specific settings

What it means

When a classification request's type resolves to "knn", Weaviate validates the request's settings via parseKNNSettings and wraps any resulting error with "parse knn specific settings" (usecases/classification/classifier.go:300). This means the settings object supplied for the built-in KNN classifier was structurally invalid — not an object, or settings.k not a number/integer.

Source

Thrown at usecases/classification/classifier.go:300

	}
	if classification == nil {
		return nil, nil
	}
	if err := c.authorizer.Authorize(ctx, principal, authorization.READ, authorization.CollectionsMetadata(classification.Class)...); err != nil {
		return nil, err
	}
	return classification, nil
}

func (c *Classifier) parseAndSetDefaults(params *models.Classification) error {
	if params.Type == "" {
		defaultType := "knn"
		params.Type = defaultType
	}

	if params.Type == "knn" {
		if err := c.parseKNNSettings(params); err != nil {
			return errors.Wrapf(err, "parse knn specific settings")
		}
		return nil
	}

	if c.modulesProvider != nil {
		if err := c.modulesProvider.ParseClassifierSettings(params.Type, params); err != nil {
			return errors.Wrapf(err, "parse %s specific settings", params.Type)
		}
		return nil
	}

	return nil
}

func (c *Classifier) parseKNNSettings(params *models.Classification) error {
	raw := params.Settings
	settings := &ParamsKNN{}
	if raw == nil {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Send settings as a JSON object, e.g. {"type":"knn","settings":{"k":3}}
2. Ensure settings.k is a JSON integer, not a string or float
3. Omit settings entirely to accept the defaults (k=3)
4. Check the inner wrapped error for the precise field that failed

Example fix

// before
{"class":"Article","type":"knn","settings":{"k":"3"}}
// after
{"class":"Article","type":"knn","settings":{"k":3}}

// client-side preflight for knn classification settings
function validateKnnSettings(body) {
  const s = body.settings
  if (s === undefined || s === null) return true // defaults apply
  if (typeof s !== 'object' || Array.isArray(s)) return false
  if ('k' in s && (!Number.isInteger(s.k) || typeof s.k !== 'number')) return false
  return true
}

function isKnnSettings(s) {
  return s == null || (typeof s === 'object' && !Array.isArray(s) &&
    (!('k' in s) || Number.isInteger(s.k)))
}

try {
  await weaviate.classifications
    .scheduler()
    .withType('knn')
    .withSettings({ k: 3 })
    .withClassName('Article')
    .do()
} catch (err) {
  if (String(err).includes('parse knn specific settings')) {
    // reschedule with valid integer settings { k: 3 }
  }
  throw err
}

When it happens

Trigger: POST /v1/classification with type "knn" (or no type, which defaults to knn) and a settings payload that is not a JSON object, or whose settings.k is a string/float/non-integer number, or missing entirely while malformed.

Common situations: Client sends "settings": "knn" (string) instead of an object; sends {"k": "3"} (string instead of number); sends {"k": 3.5} where Int64() parsing fails; older clients using a settings shape from a different classifier type.

Related errors

• settings.%s must be number, got %T
• role name is required
• permission is required
• base backup cannot be the same as the new backup ID: %s
• classifications are not supported in the current cluster con

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/0f93f39cf4394830. Report an issue: GitHub.