Pitfalls

Project Configuration

Understanding startup crashes due to malformed configs in Monospace.

Monospace relies heavily on config.yaml and environment variables. Because configuration dictates the structure of the system database, file storage connectors, and email providers, missing or malformed configuration behaves fatally.

The Pitfall

Invalid environment variables, such as a missing DIRECTUS_KMS__MASTER_KEY or incomplete connector settings, will cause the application to crash on startup. Core connectors like the system database and file storage have no graceful degradation fallbacks. The emailer is the one exception - if unconfigured, the server starts with a warning and email features are disabled.

Mitigation

Always ensure your environment variables are correctly spelled and all required settings for a provider (such as host, port, user, and password for Postgres) are successfully populated in the environment before boot. Keep a strict .env.example file synced with your config.yaml requirements.

Edit this pageorReport an issue

Concurrent Migrations

Details about the lack of distributed locks for schema migrations in Monospace.

Overly Permissive Public Roles

The dangers of granting excessive permissions to public roles in Monospace.