Skip to main content

CRE-2025-0105

SpiceDB Datastore Startup FailureHigh
Impact: 9/10
Mitigation: 3/10

CRE-2025-0105View on GitHub

Description

Detects critical failures where a SpiceDB instance cannot start due to an invalid schema or an uninitialized datastore during the bootstrap process. This is a common configuration error that prevents the service from initializing and serving requests, leading to a total service outage.


Cause

  • Invalid Schema: The schema provided to `--datastore-bootstrap-files` contains syntactical or semantic errors, such as referencing a non-existent object type (`undefined object type user`).
  • Uninitialized Datastore: The datastore (e.g., Postgres) has not been properly migrated before bootstrap. SpiceDB attempts to query for existing data before its own tables (like `namespace_config`) have been created, resulting in an error like `relation "namespace_config" does not exist`. This is the specific failure you reproduced.

Mitigation

IMMEDIATE RESPONSE:

  • Examine the SpiceDB container logs for a `FATAL` or `ERROR` level message.
  • The error is `relation "namespace_config" does not exist`:** The datastore is uninitialized. For a fresh deployment, add the `--datastore-bootstrap-overwrite` flag to the SpiceDB `serve` command to force the database migration to run before bootstrapping the schema.
  • If the error is `undefined object type` or `schema parsing error`: The schema itself is invalid. Retrieve the schema file, validate it using the `zed validate <file>` command, correct the errors, and redeploy.

PREVENTIVE MEASURES:

  • Integrate `zed validate` into your CI/CD pipeline to automatically check all schema changes before deployment.
  • Use the `--datastore-bootstrap-overwrite` flag in startup commands for all initial/fresh deployments to ensure tables are created correctly.
  • Implement robust health checks that validate the service is not only running but also responsive to basic API calls after startup.

References