[lightdash-bot]

Docs changes Cloudy's docs writer made from support threads on Friday 30 October 2026. One commit per change, described below in order; review by commit and comment on any to drop or change. Every commit builds on current main, so merge whenever it is green, including midday for an urgent fix: later changes that day start a new PR.

---

Document how to troubleshoot the self-hosted usage analytics nightly refresh

Pages

• Updates the existing Usage analytics page

What changes

• New Troubleshoot the nightly refresh section under Verify setup
• Explains the 00:30 UTC job, its Usage processing stage started/finished log pairs and outcomes
• Explains the users stage, its log lines, and why People can be empty while other dashboards have data
• Explains the 7-day window, the 5,000-partition cap, and checking license/storage access first

Why

Self-hosted admins had no way to tell from docs whether the nightly usage-processing job ran, what its log lines mean, or why the People dashboards specifically can stay empty while others have data.

Checked against

• packages/backend/src/analytics/eventStream/UsageEventsCompactor.ts
• packages/backend/src/analytics/eventStream/UsageUserActivityBuilder.ts
• packages/backend/src/analytics/eventStream/usageProcessingWindow.ts
• packages/backend/src/scheduler/SchedulerWorker.ts
• packages/backend/src/config/parseConfig.ts

Cloudy found this docs gap while working a support thread. Started from this internal Slack thread (Lightdash workspace only).

---

Note that there's no admin view of personal warehouse credentials

Pages

• Updates the existing Personal warehouse connections page

What changes

• Personal warehouse connections: notes there's no admin view/API of who has personal credentials configured

Why

Admins planning personal credential rollout had no documented answer on whether they could see who had configured credentials for a project.

Checked against

• packages/backend/src/controllers/projectController.ts
• packages/backend/src/services/ProjectService/ProjectService.ts
• packages/backend/src/models/UserWarehouseCredentials/UserWarehouseCredentialsModel.ts

A teammate answered a support question that the docs should have covered. Started from this internal Slack thread (Lightdash workspace only).

---

Document that service accounts can't hold or use personal warehouse credentials

Pages

• Updates the existing Service accounts page

What changes

• New Limitations section on the service accounts reference page
• States a service account can't run queries against a project requiring personal warehouse credentials
• Points readers to a shared connection or a real Lightdash user as the alternative

Why

The service accounts reference page didn't say whether a service account could hold or use warehouse credentials, leaving readers evaluating it for per-user warehouse access with no documented answer.

Checked against

• packages/backend/src/services/ProjectService/ProjectService.ts
• packages/backend/src/ee/authentication/serviceAccount.mock.ts
• packages/common/src/types/warehouseConnections.ts
• packages/backend/src/services/WarehouseClientFactory/personalCredentialOverlay.ts

A teammate answered a support question that the docs should have covered. Started from this internal Slack thread (Lightdash workspace only).

---

Document API-based service account provisioning

Pages

• Updates the existing Service accounts page

What changes

• New Automate account provisioning section: calling create-service-account headlessly, request shapes, curl example
• Warns the token only returns on create/rotate, and creation isn't idempotent so don't retry a timed-out POST
• Notes manage:Organization is required, so a scoped service account token can't provision more accounts
• Instance initialization says the bootstrap token creates a one-time org-admin account reconciliation can delete

Why

The service accounts page covered UI creation and a generic API auth snippet but had no guidance for provisioning accounts through the API, and understated the risk of leaving the LD_SETUP_SERVICE_ACCOUNT_TOKEN bootstrap configured.

Checked against

• packages/backend/src/ee/controllers/serviceAccountsController.ts
• packages/backend/src/auth/account/account.ts
• packages/backend/src/services/InstanceConfigurationService/InstanceConfigurationService.ts
• packages/common/src/ee/serviceAccounts/types.ts
• packages/common/src/authorization/organizationMemberAbility.ts

Cloudy found this docs gap while working a support thread. Started from this internal Slack thread (Lightdash workspace only).

---

Document that the Helm chart's automatic scale-down needs helm upgrade, not GitOps syncs

Pages

• Updates the existing Upgrade your instance page

What changes

• Set the upgrade mode: automatic scale-down only runs under helm upgrade, not ArgoCD/Flux template syncs
• Scale workloads down by hand, when required: now also required for GitOps deployments on UNSAFE

Why

Readers applying the Helm chart through ArgoCD or Flux's template mode had no way to know the chart's automatic scale-down silently never runs for them, so they could upgrade an UNSAFE release with old pods still live against the new schema.

Cloudy found this docs gap while working a support thread. Started from this internal Slack thread (Lightdash workspace only).

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
lightdash	🟢 Ready	View Preview	Oct 30, 2026, 9:47 AM

[github-actions]

Documentation validation

✅ All blocking checks passed.

Component system

0 finding(s) across the corpus.

Findings on lines this pull request touched are annotated inline in Files changed.

View the validation run.