How to fix Chef Habitat On-Prem Builder-API Startup Failure due to public schema error for hosted Postgres database?

This article is applicable for Chef Habitat with hosted Postgres database. 

Cause

Builder-API runs migration logic at startup. If the configured Builder DB role cannot create objects in schema public on the hosted Postgres database, migrations fail and service startup aborts.

Chef Habitat On-Prem Builder API can fail during startup if the Builder database role lacks the required USAGE and CREATE privileges on PostgreSQL’s default public schema. Because database migrations run as part of startup, insufficient schema permissions can prevent migrations from completing and cause the service to exit with a panic, even when the database connection details are otherwise correct.

Restoring the required schema privileges allows Chef Habitat Builder’s startup migrations to create or update the necessary database objects.

Root cause

Chef Habitat Builder API runs migration logic at startup. These migrations create or alter database objects as part of service initialization.

If the Hab Builder database role does not have sufficient privileges on the public schema, migrations fail and the service aborts. This is a schema-level issue, not a basic connectivity issue.

Why this affects Chef Habitat Builder

The documented Builder deployment configuration describes connection parameters such as host, port, username, database name, and password. Chef Habitat Builder is effectively expected to use PostgreSQL's default public schema. If a security policy removes USAGE or CREATE from that schema, startup jobs can fail even though the server, database, and credentials are correct.

Resolution

Grant the required permissions back to the Builder database user.

Step 1: Connect with PostgreSQL admin access

Use a database role that can inspect and modify schema grants.

Step 2: Restore schema privileges

Run: GRANT USAGE, CREATE ON SCHEMA public TO your_builder_user;

If your environment applies tighter restrictions, ensure the Builder DB role still has the minimum rights required to create and manage objects in the public schema.

Step 3: Restart Builder services

Restart the Builder API and related Habitat services so the startup migration runs again under the corrected privileges.

Validation

After the privileges are restored and services are restarted, confirm the following:

• Builder API starts successfully
• Logs no longer contain permission denied for schema public
• Chef Habitat Frontend becomes available again
• Related services and API calls are healthy

Prevention

To reduce recurrence:

• Include PostgreSQL schema privilege checks in hardening and compliance reviews
• Revalidate Builder DB grants after security policy changes or PostgreSQL upgrades
• Document the minimum privileges required for the Builder database role
• Review hosted PostgreSQL permission changes before enforcing them in shared or production environments

Important note

This issue is not caused by a wrong database host, username, password, or database name. It is caused by a missing schema privilege required during startup migration. Restoring USAGE and CREATE on public for the Builder DB user is the correct remediation when the current configuration expects the standard PostgreSQL default schema.