{"record":{"id":"60db93fc05455b4f","repo":"weaviate/weaviate","slug":"twelvelabs-api-key","errorCode":null,"errorMessage":"TwelveLabs API Key","messagePattern":"TwelveLabs API Key","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/multi2vec-twelvelabs/clients/twelvelabs.go","lineNumber":165,"sourceCode":"\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn extractEmbedding(res.ImageEmbedding)\n}\n\nfunc extractEmbedding(emb *embedding) ([]float32, error) {\n\tif emb == nil || len(emb.Segments) == 0 || len(emb.Segments[0].Float) == 0 {\n\t\treturn nil, errors.New(\"empty embeddings response\")\n\t}\n\treturn emb.Segments[0].Float, nil\n}\n\nfunc (v *vectorizer) doEmbed(ctx context.Context, baseURL, model string,\n\twriteInput func(*multipart.Writer) error,\n) (*embedResponse, error) {\n\tapiKey, err := v.getApiKey(ctx)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"TwelveLabs API Key\")\n\t}\n\n\tbody := &bytes.Buffer{}\n\twriter := multipart.NewWriter(body)\n\tif err := writer.WriteField(\"model_name\", model); err != nil {\n\t\treturn nil, errors.Wrap(err, \"write model_name field\")\n\t}\n\tif err := writeInput(writer); err != nil {\n\t\treturn nil, errors.Wrap(err, \"write input field\")\n\t}\n\tif err := writer.Close(); err != nil {\n\t\treturn nil, errors.Wrap(err, \"close multipart writer\")\n\t}\n\n\turl := fmt.Sprintf(\"%s/embed\", baseURL)\n\treq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, body)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"create POST request\")","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/modules/multi2vec-twelvelabs/clients/twelvelabs.go#L147-L183","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Set the TWELVELABS_APIKEY environment variable before starting Weaviate and restart it","Send the X-TwelveLabs-Api-Key header on the GraphQL/REST request for per-request credentials","Verify the env var is actually visible in the Weaviate process (docker-compose environment block or k8s envFrom)","Confirm the header name spelling: X-TwelveLabs-Api-Key (case-insensitive lookup, but name must match)"],"exampleFix":"// before (client request without header, no env var)\nresult, err := client.GraphQL().Get().NearImage(...) // -> TwelveLabs API Key: no api key found...\n// after\nreq := client.GraphQL().Get().NearImage(...)\nreq = req.WithHeader(\"X-TwelveLabs-Api-Key\", os.Getenv(\"MY_TWELVELABS_KEY\"))","handlingStrategy":"validation","validationCode":"// Client-side (JS v4): ensure the header or server env is set before querying\nif (!process.env.TWELVELABS_APIKEY) {\n  throw new Error(\"Set TWELVELABS_APIKEY or send X-TwelveLabs-Api-Key header\");\n}\nconst res = await collection.query.nearImage(...)\n  .withHeader?.(\"x-twelvelabs-api-key\", process.env.TWELVELABS_APIKEY);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set TWELVELABS_APIKEY in the Weaviate deployment's environment (docker-compose/k8s secret) before enabling the module","Prefer per-request X-TwelveLabs-Api-Key headers in multi-tenant setups","Add a startup healthcheck that performs a trivial embedding to fail fast on missing keys"],"tags":["api-key","authentication","twelvelabs","config"],"backgroundTag":"missing-api-key","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}