ChromaCloud::Metadata length too large (default max is ${thi

Error message

ChromaCloud::Metadata length too large (default max is ${this.limits.maxMetadataBytes}). Got ${JSON.stringify(testSubmission.metadata).length}. Upsert may fail!

What it means

ChromaCloud.smartAdd() also enforces the maxMetadataBytes quota (4096): it JSON.stringify()s the first record's metadata object and warns when the serialized JSON exceeds that length, meaning the cloud upsert will likely be rejected with 422. Only submission.metadatas[0] is sampled per batch, and the limit counts the whole serialized object (keys, quotes, braces included), not a single field.

Source

Thrown at server/utils/vectorDbProviders/chromacloud/index.js:78

      id: submission.ids[0],
      embedding: submission.embeddings[0],
      metadata: submission.metadatas[0],
      document: submission.documents[0],
    };

    if (testSubmission.embedding.length > this.limits.maxEmbeddingDim)
      console.warn(
        `ChromaCloud::Embedding dimension too large (default max is ${this.limits.maxEmbeddingDim}). Got ${testSubmission.embedding.length}. Upsert may fail!`
      );
    if (testSubmission.document.length > this.limits.maxDocumentBytes)
      console.warn(
        `ChromaCloud::Document length too large (default max is ${this.limits.maxDocumentBytes}). Got ${testSubmission.document.length}. Upsert may fail!`
      );
    if (
      JSON.stringify(testSubmission.metadata).length >
      this.limits.maxMetadataBytes
    )
      console.warn(
        `ChromaCloud::Metadata length too large (default max is ${this.limits.maxMetadataBytes}). Got ${JSON.stringify(testSubmission.metadata).length}. Upsert may fail!`
      );

    // If the submissions are not too large, just add them directly.
    if (submission.ids.length <= this.limits.maxRecordsPerWrite) {
      await collection.add(submission);
      return true;
    }

    this.logger(
      `Upsert Payload is too large (max is ${this.limits.maxRecordsPerWrite} records). Splitting into chunks of ${this.limits.maxRecordsPerWrite} records.`
    );
    const chunks = [];
    let chunkedSubmission = {
      ids: [],
      embeddings: [],
      metadatas: [],
      documents: [],

View on GitHub (pinned to 3aec848f28)

Solutions

Trim metadata before upload: keep string fields short (truncate URLs/titles to a few hundred chars) and drop non-essential keys so the total JSON stays under 4 KB.
Move bulky content (excerpts, long descriptions) into the document text or a separate store — metadata should hold small filterable scalars.
Re-embed the affected documents after cleaning metadata; previously rejected records are not retried automatically.
If the metadata genuinely must be large, self-host Chroma (VECTOR_DB=chroma) or pick a provider without a metadata byte quota.

Example fix

// before: full URL + description pushed into metadata
await collection.add({
  ids: [docId],
  documents: [text],
  metadatas: [{ url: longCanonicalUrl, description: fullPageDescription, ...rest }], // JSON > 4096 chars
});

// after: clamp metadata before upsert
const clampMetadata = (meta, maxJson = 4096) => {
  const out = {};
  for (const [k, v] of Object.entries(meta))
    out[k] = typeof v === "string" && v.length > 256 ? v.slice(0, 256) : v;
  if (JSON.stringify(out).length > maxJson)
    throw new Error(`metadata still too large after clamping`);
  return out;
};
await collection.add({ ids: [docId], documents: [text], metadatas: [clampMetadata(meta)] });

Defensive patterns

Strategy: validation

Validate before calling

const CHROMA_CLOUD_MAX_METADATA_JSON = 4096;

function clampMetadata(metadata) {
  const out = {};
  for (const [key, value] of Object.entries(metadata)) {
    out[key] =
      typeof value === "string" && value.length > 256
        ? value.slice(0, 256)
        : value;
  }
  if (JSON.stringify(out).length > CHROMA_CLOUD_MAX_METADATA_JSON) {
    throw new Error("Metadata exceeds Chroma Cloud 4 KB quota even after clamping — move data into document text.");
  }
  return out;
}

Prevention

Treat vector-store metadata as short filterable scalars only (title, source, type, dates) — never page content, base64, or full URLs with query strings.
Truncate long string fields at ingestion time; the limit counts the whole JSON.stringify output, including keys and punctuation.
When migrating from a local vector DB to a cloud one, run a metadata size audit over existing records before the first sync.

When it happens

Trigger: Uploading documents whose per-record metadata contains very long strings — full scraped URLs with long query strings, entire descriptions or page excerpts, base64 blobs, tag dumps — or dozens of keys, pushing JSON.stringify(metadata).length past 4096 on the sampled first record.

Common situations: Custom metadata injected at upload time via the API, web-scrape data sources carrying long canonical URLs/titles, workspaces migrated from local Chroma (no metadata limit), and metadata that grew incrementally as more fields (tag, topic, source) were appended per document.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

AI-assisted analysis of Mintplex-Labs/anything-llm@3aec848f28 (2026-08-18). Data as JSON: /api/errors/fd8eff1557e930a2. Report an issue: GitHub.