Enabling Fleet and Polly on self-hosted LangSmith after a v0.15 upgrade

Last updated: June 23, 2026

Symptom

You upgrade self-hosted LangSmith to v0.15 and set fleet.enabled: true (and/or polly.enabled: true) in your Helm values. helm upgrade fails before any Kubernetes resources change:

Error: UPGRADE FAILED: execution error at (langsmith/templates/validate.yaml:266:4):
fleet.encryptionKey is required when fleet.enabled is true
(not needed if config.existingSecretName is set with the key already present)

Polly has the same key requirement, but it does not surface in this exact error. If you skip the Polly key, Polly won't enable either.

Cause

Fleet stores sensitive data at rest and needs its own encryption key. The Helm chart enforces this at template-render time in langsmith/templates/validate.yaml:266. The check fires when fleet.enabled: true is set and neither fleet.encryptionKey nor config.existingSecretName (pointing at a Secret that already contains the key) is supplied.

Polly works the same way and needs its own key. The Fleet and Polly keys must be different values; you cannot reuse one for both.

Fleet and Polly have existed since v0.13, so the key requirement is not new in v0.15. What changed in v0.15 is that several Helm keys were renamed from the old "Agent Builder" names to "Fleet" names. Copying stale values from a pre-v0.15 config can silently pass wrong key names. See KB article #4a05a14e for the full rename mapping.

Resolution

1. Upgrade one minor version at a time

Do not jump from v0.13 straight to v0.15. Each minor version runs database migrations in order; skipping versions can leave migrations unapplied or out of order. Back up the database first. Migrations run automatically and require brief downtime.

Path: v0.13.x → v0.14.x → v0.15.x.

# Stage 1: upgrade to latest v0.14
helm upgrade langsmith langchain/langsmith \
  --version 0.14.6 \
  --namespace <namespace> \
  --values /path/to/langsmith-values.yaml

# Stage 2: confirm health, then upgrade to v0.15
helm upgrade langsmith langchain/langsmith \
  --version 0.15.0-rc.13 \
  --namespace <namespace> \
  --values /path/to/langsmith-values-updated.yaml

v0.14 adds a new pod for queue ingestion. A new workload appearing after the v0.14 upgrade is expected.

2. Generate two encryption keys

Generate a fresh random key for Fleet and a separate one for Polly:

# Fleet
openssl rand -base64 32

# Polly (must differ from the Fleet key)
openssl rand -base64 32

Treat both as secrets. If you lose them or rotate them without a plan, encrypted data becomes unreadable.

3. Add the keys to your Helm values

Option A — inline in the values file:

fleet:
  enabled: true
  encryptionKey: "<fleet-base64-key>"

polly:
  enabled: true
  encryptionKey: "<polly-base64-key>"

Option B — pre-existing Kubernetes Secret:

config:
  existingSecretName: "langsmith-fleet-polly-secrets"

When config.existingSecretName is set and the Secret already contains the relevant keys, the validation at validate.yaml:266 does not fire and inline fleet.encryptionKey is not required. Prefer Option B for production so keys do not live in a values file checked into version control.

The full list of Helm keys required for Fleet and Polly in v0.15 is in the official "Enable Fleet Insights and Polly" docs anchor in References.

4. Re-run helm upgrade

helm upgrade langsmith langchain/langsmith \
  --version <target-v0.15-version> \
  --namespace <namespace> \
  --values /path/to/langsmith-values-updated.yaml

5. Verify in the UI

  • Polly: the Polly / LangSmith Engine section should appear in the UI right after a successful upgrade.

  • Fleet: the Fleet (Agent Builder) section should appear. If it doesn't, check that Fleet pods started and are healthy.

Split control plane / data plane

For deployments where the control plane and data plane run in separate clusters or cloud accounts:

  • Apply Fleet and Polly Helm values to the control plane chart.

  • The data plane does not need separate Fleet or Polly config for basic enablement.

  • Upgrade the control plane first, then upgrade the data plane independently.

Common pitfalls

  • Skipping minor versions. Always go v0.13 → v0.14 → v0.15. Migrations are incremental and order-dependent.

  • Reusing one key for Fleet and Polly. Each feature needs its own distinct key.

  • Stale "Agent Builder" key names. v0.15 renamed several Helm keys; old names are silently ignored. See KB #4a05a14e.

  • No database backup. Migrations are not reversible without one.

  • Plaintext keys in values files. Use config.existingSecretName in production.

References