Troubleshooting Organization Changes in Self-Hosted Data Planes

Last updated: January 21, 2026

Summary

When creating or renaming an organization in a self-hosted Braintrust data plane deployment (Helm, Terraform, etc.), the orgName environment variable must be updated in the deployment configuration to match the new organization name. Failure to update this configuration causes a mismatch between the organization name in the Braintrust control plane and the data plane, resulting in 403 authorization errors and abnormal dashboard behavior. This issue is specific to self-hosted data plane deployments and does not affect cloud-hosted instances.

Symptoms

403 Forbidden errors when accessing the dashboard after organization creation or rename
Dashboard displays abnormal or broken behavior for the old organization name
Unable to view data or metrics for the organization
Authentication issues when accessing organization resources

Workarounds

Option 1: Update Helm Configuration

For Helm deployments, update the orgName field in your values.yaml file to match the new organization name and redeploy the instance.

Helm Configuration


# values.yaml
global:
  orgName: "Your New Organization Name"  # Update to match the organization name in Braintrust
  # ... other configuration options

After updating the configuration file, redeploy your Helm release:


helm upgrade braintrust braintrust/braintrust -f values.yaml -n braintrust

Option 2: Update Terraform Configuration

For Terraform deployments, update the organization name variable in your Terraform configuration and apply the changes.

Terraform Configuration


# main.tf or variables.tf
variable "org_name" {
  description = "Organization name"
  type        = string
  default     = "Your New Organization Name"  # Update to match the organization name in Braintrust
}

# Pass this variable to your Braintrust deployment module
module "braintrust" {
  source   = "..."
  org_name = var.org_name
  # ... other configuration
}

Apply the Terraform changes:


terraform plan
terraform apply

Notes

This issue only affects self-hosted data plane deployments. Cloud-hosted instances managed by Braintrust do not require manual environment variable updates.
The orgName configuration must exactly match the organization name as it appears in the Braintrust control plane, including capitalization and spacing.
After updating the configuration, a full redeployment of the data plane is required for changes to take effect.
If you rename an organization, update the orgName configuration immediately to prevent service disruption.
When creating a new organization in a self-hosted environment, ensure the orgName is set correctly before the organization is actively used.
Dashboard issues will resolve immediately once the correct orgName configuration is deployed.