weaviate/weaviate · warning

missing required url param 'additional'

Error message

missing required url param 'additional'

What it means

The internal GET object handler requires the query parameter 'additional' (base64-encoded JSON of additional.Properties). If the parameter is absent or empty, the handler responds 'missing required url param additional' with HTTP 400. The internal protocol always sends it; its absence means the caller did not follow the internal API contract.

Source

Thrown at adapters/handlers/rest/clusterapi/indices.go:503

	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		args := i.regexpObject.FindStringSubmatch(r.URL.Path)
		if len(args) != 4 {
			http.Error(w, "invalid URI", http.StatusBadRequest)
			return
		}

		index, shard, id := args[1], args[2], args[3]

		defer r.Body.Close()

		if r.URL.Query().Get("check_exists") != "" {
			i.checkExists(w, r, index, shard, id)
			return
		}

		additionalEncoded := r.URL.Query().Get("additional")
		if additionalEncoded == "" {
			http.Error(w, "missing required url param 'additional'",
				http.StatusBadRequest)
			return
		}

		additionalBytes, err := base64.StdEncoding.DecodeString(additionalEncoded)
		if err != nil {
			http.Error(w, "base64 decode 'additional' param: "+err.Error(),
				http.StatusBadRequest)
			return
		}

		selectPropertiesEncoded := r.URL.Query().Get("selectProperties")
		if selectPropertiesEncoded == "" {
			http.Error(w, "missing required url param 'selectProperties'",
				http.StatusBadRequest)
			return
		}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Always include ?additional= with the base64-encoded JSON of additional.Properties (e.g. base64 of {"vector":false}).
2. Use the official weaviate Go client / internal replication code path instead of hand-building the request.
3. If using check_exists, add the check_exists query param instead — that path skips the 'additional' requirement.
4. Compare with the request format used by the same Weaviate version's replication module to confirm parameter names.

Example fix

// before
url := fmt.Sprintf("/schema/%s/shard/%s/objects/%s", index, shard, id)
// after
addJSON, _ := json.Marshal(additional.Properties{Vector: true})
url := fmt.Sprintf("/schema/%s/shard/%s/objects/%s?additional=%s", index, shard, id,
    base64.StdEncoding.EncodeToString(addJSON))

// Build the query with url.Values so required params can't be dropped
q := url.Values{}
q.Set("additional", base64.StdEncoding.EncodeToString(addJSON))
if q.Get("additional") == "" {
    return fmt.Errorf("additional param required")
}

func hasRequiredQuery(u *url.URL) bool {
    return u.Query().Get("additional") != "" && u.Query().Get("selectProperties") != ""
}

if resp.StatusCode == http.StatusBadRequest && strings.Contains(readBody(resp), "missing required url param") {
    return fmt.Errorf("internal GET malformed: %s", readBody(resp))
}

When it happens

Trigger: GET /schema/{index}/shard/{shard}/objects/{id} without ?additional=<base64-json> (and without check_exists), e.g. a hand-written replication client or curl probe omitting the parameter.

Common situations: Manual testing with curl/browser against the internal port, custom replication code written against an older internal protocol that made 'additional' optional, or URL construction dropping query parameters.

Related errors

• missing required url param 'selectProperties'
• base64 decode 'additional' param:
• base64 decode 'selectProperties' param:
• unmarshal 'additional' param from json:
• unmarshal 'selectProperties' param from json:

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