Skip to Content
DevelopersTroubleshooting

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

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

Last updated on