Troubleshooting
Run stratolms doctor from the course project directory after setup or when a
build reports missing configuration. It checks the generated StratoLMS config,
required environment variables, the current Node.js version, package manager,
canonical site URL, adapter requirements, and optional payment features. The
command reads .env and .dev.vars locally but never prints their contents.
Each finding includes a stable code, severity, next action, and a link to the
relevant section below. Fix error findings and run the command again. Advice
findings describe a limitation or maintenance recommendation and do not make a
working setup fail. With --json, stdout contains one JSON document with the
same findings and an additive diagnosticSummary containing only tool versions,
the adapter name, and finding codes. Review that summary before sharing it.
Configuration
Section titled “Configuration”For missing-config, run stratolms setup or restore stratolms.config.mjs
from the generated project. For config-load, check that the file is valid
JavaScript and that imports it uses are installed. The doctor deliberately does
not repeat exception text from config loading because it could contain private
values.
Findings with codes such as invalid, unknown-key, config/prerequisite, and
memory-store point to invalid or unsupported config fields. Compare the
generated file with the examples in stratolms.config.mjs, then rerun the doctor.
Secrets and environment variables
Section titled “Secrets and environment variables”missing-env and short-env findings name the variable that needs attention,
but never include its value. Set it in your deployment’s secret manager or local
.env file. Do not commit .env or paste it into an issue. A
placeholder-env finding means STRATO_SECRET still begins with a common
placeholder word; run stratolms setup to generate a random value.
Runtime
Section titled “Runtime”StratoLMS requires Node.js 22.19.0 or later. If node-version appears, switch
to a supported Node release and rerun stratolms doctor.
Package manager
Section titled “Package manager”The generated site pins pnpm in package.json. A package-manager advice
finding means that declaration is missing or does not use a pinned pnpm version.
Use the version recorded in the generated project, commonly through Corepack.
This finding is informational and does not change the runtime check result.
Canonical URL
Section titled “Canonical URL”canonical-url means PUBLIC_SITE_URL is not a site origin accepted by the
starter. Set it to an HTTPS origin such as https://courses.example.com, with
no path, query, or fragment. Localhost may use HTTP during development.
Adapter setup
Section titled “Adapter setup”adapter appears when D1 or R2 media is enabled without the Cloudflare adapter.
Choose the Cloudflare adapter in the generated project’s astro.config.mjs and
install its package using the package manager already declared by the project.
Payments and email
Section titled “Payments and email”payment-provider means PAYMENT_PROVIDER is not one of polar,
lemonsqueezy, or stripe. Set it to the provider configured for the course.
email-delivery means a sender address or email API key is missing. Set
EMAIL_FROM and RESEND_API_KEY in the runtime secret configuration. Dashboard
sign-in and paid delivery depend on email being available.
Recovery
Section titled “Recovery”recovery-unavailable is advice: the selected provider has no built-in licence
recovery adapter. Returning buyers need an owner support route after their
access links expire. It does not make an otherwise valid provider setup fail.
recovery-unconfigured is an error for Polar recovery. Set
POLAR_ORGANIZATION_ID and provide published courses with
pricing.licenseBenefitId values. See payments for the
provider setup details.
Database connection
Section titled “Database connection”database-url appears when PostgreSQL progress storage is enabled without
DATABASE_URL. Set the connection string in the deployment’s secret manager;
do not put a real credential in a bug report.
Owner email
Section titled “Owner email”owner-emails means OWNER_EMAILS is missing or has an invalid address. Set a
comma-separated list of owner addresses before enabling dashboard sign-in.
Content Security Policy
Section titled “Content Security Policy”csp means one or more configured CSP additions failed validation. Review the
csp.additions entries in stratolms.config.mjs. Add only the external origins
required by the course site’s integrations.
Sharing a bug report
Section titled “Sharing a bug report”Use the bug report form
and include the smallest reproduction, StratoLMS and Node.js versions, package
manager, and adapter. You may include diagnosticSummary from
stratolms doctor --json; review it before posting. Never include .env,
tokens, learner IDs, customer data, private exports, or private file paths.