Skip to content

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.

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.

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.

StratoLMS requires Node.js 22.19.0 or later. If node-version appears, switch to a supported Node release and rerun stratolms doctor.

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 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 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.

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-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-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-emails means OWNER_EMAILS is missing or has an invalid address. Set a comma-separated list of owner addresses before enabling dashboard sign-in.

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.

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.