Troubleshooting
Check the terminal and browser console for the first error. Do not publish environment files, passwords, tokens, or sign-in codes.
Installation fails
Check your Node.js version:
node --versionUse Node.js 24.21.0 or later. Run the installer with npx if the command
is not on your PATH. Use a valid npm package name, such as my-cms-app.
Database or migration fails
Check the variables for your database plugin. Check database access from the environment that runs bootstrap. Production builds must not use the development database flag.
Read the migration error before you change the database. Do not delete the database or lockfile to fix an unknown error. Back up production data before you change its schema.
Sign-in fails
Check the authentication settings. Confirm that the user exists in the CMS.
Automatic signup is disabled. Bootstrap creates the initial admin from MASTER_EMAIL if that email
does not exist.
Request a new sign-in code if the previous code expires. In development, find the code in the server terminal. In production, check your email provider settings and sender verification.
Editor or API fails
Confirm that the server is running. Confirm that BETTER_AUTH_URL matches the site’s public URL.
Check that the framework plugin is in oberon/config.ts. Check the
CMS API route. The API route serves plugin handlers; it is not
a general /cms/api/site endpoint.
Image upload fails
Check your storage plugin and provider credentials. Confirm that its handler is available through the CMS API route. Sign in with a user who can write images.
Tailwind styles are missing
Check that the plugin is in oberon/config.ts. Check the
stylesheet setup. The plugin reads className values from published page
data. It does not scan component source files.
Build or deployment fails
Check the first build error and the host’s logs. Confirm that the build environment has the required credentials. Use the deployment guide and your framework’s build instructions.
If the problem remains, search GitHub Issues . Include the error, package versions, and steps to reproduce it. Remove secrets before you submit logs.