Runbook: Provisioning Failures

Symptoms and diagnosis

1. "No schema found" when accessing new org

The user can log in, but any request to fetch records results in a "Schema [slug] does not exist" error.

• Cause: The Organization.Created event may have failed before the CREATE SCHEMA command succeeded.
• Check: Run SELECT * FROM information_schema.schemata WHERE schema_name = 'the-slug'; on the main DB.

2. Entity metadata missing (Empty UI)

The schema exists, but the user sees no "Entities" in the sidebar.

• Cause: The migrations or seeding phase failed.
• Check: Check the server logs for "Error in organizationCreatedSubscriber".

Recovery procedures

Manual re-provisioning

To manually run the provisioning logic for a specific organization, you can use the internal helper scripts or invoke the subscriber directly via a REPL:

import { organizationCreatedSubscriber } from '@/features/pub-sub/subscribers/organization-created';

// Manually trigger the subscriber with the required payload
await organizationCreatedSubscriber({ 
  organization: { id: 'org_id_here', slug: 'my-org-slug' } 
});

Partial re-seeding

If you only need to re-run the default data seeds (e.g., you added new default fields to the product), you can emit a Organization.Seed event:

import { seedOrganizationSubscriber } from '@/features/pub-sub/subscribers/seeding';

await seedOrganizationSubscriber({ slug: 'my-org-slug' });

Best practices

• Monitor Logs: All provisioning errors are logged with console.error. In production, these should trigger alerts.
• Check Connection Limits: If creating many orgs simultaneously, ensure the database user has a high enough connection limit to handle the concurrent migrations.