weaviate/weaviate · error

TwelveLabs API Key

Error message

TwelveLabs API Key

What it means

This wrapper error is thrown in doEmbed when getApiKey fails to resolve a TwelveLabs API key. The key is looked up first in the per-request header X-TwelveLabs-Api-Key, then in the server-level TWELVELABS_APIKEY environment variable. If neither is set, the request cannot be authenticated and embedding is aborted before any HTTP call is made.

Source

Thrown at modules/multi2vec-twelvelabs/clients/twelvelabs.go:165

	if err != nil {
		return nil, err
	}
	return extractEmbedding(res.ImageEmbedding)
}

func extractEmbedding(emb *embedding) ([]float32, error) {
	if emb == nil || len(emb.Segments) == 0 || len(emb.Segments[0].Float) == 0 {
		return nil, errors.New("empty embeddings response")
	}
	return emb.Segments[0].Float, nil
}

func (v *vectorizer) doEmbed(ctx context.Context, baseURL, model string,
	writeInput func(*multipart.Writer) error,
) (*embedResponse, error) {
	apiKey, err := v.getApiKey(ctx)
	if err != nil {
		return nil, errors.Wrap(err, "TwelveLabs API Key")
	}

	body := &bytes.Buffer{}
	writer := multipart.NewWriter(body)
	if err := writer.WriteField("model_name", model); err != nil {
		return nil, errors.Wrap(err, "write model_name field")
	}
	if err := writeInput(writer); err != nil {
		return nil, errors.Wrap(err, "write input field")
	}
	if err := writer.Close(); err != nil {
		return nil, errors.Wrap(err, "close multipart writer")
	}

	url := fmt.Sprintf("%s/embed", baseURL)
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, body)
	if err != nil {
		return nil, errors.Wrap(err, "create POST request")

View on GitHub (pinned to 75aa4b6d11)

Solutions

  1. Set the TWELVELABS_APIKEY environment variable before starting Weaviate and restart it
  2. Send the X-TwelveLabs-Api-Key header on the GraphQL/REST request for per-request credentials
  3. Verify the env var is actually visible in the Weaviate process (docker-compose environment block or k8s envFrom)
  4. Confirm the header name spelling: X-TwelveLabs-Api-Key (case-insensitive lookup, but name must match)

Example fix

// before (client request without header, no env var)
result, err := client.GraphQL().Get().NearImage(...) // -> TwelveLabs API Key: no api key found...
// after
req := client.GraphQL().Get().NearImage(...)
req = req.WithHeader("X-TwelveLabs-Api-Key", os.Getenv("MY_TWELVELABS_KEY"))
Defensive patterns

Strategy: validation

Validate before calling

// Client-side (JS v4): ensure the header or server env is set before querying
if (!process.env.TWELVELABS_APIKEY) {
  throw new Error("Set TWELVELABS_APIKEY or send X-TwelveLabs-Api-Key header");
}
const res = await collection.query.nearImage(...)
  .withHeader?.("x-twelvelabs-api-key", process.env.TWELVELABS_APIKEY);

Prevention

When it happens

Trigger: Calling embedText or embedImage (via Vectorize/VectorizeQuery/VectorizeImages or nearText/nearImage search) when neither the X-TwelveLabs-Api-Key request header nor the TWELVELABS_APIKEY env var is configured.

Common situations: Fresh Weaviate deployments where the module is enabled but no API key was set at startup; clients that forgot to send the X-TwelveLabs-Api-Key header; containers where the env var was not passed through (docker-compose env, k8s secret not mounted).

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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