vxcontrol/pentagi · error

failed to create extension %q in schema %q (a privileged use

Error message

failed to create extension %q in schema %q (a privileged user must run CREATE EXTENSION %s SCHEMA %s once): %w

What it means

ensureSharedExtension found that a required extension (vector, pg_trgm) is not installed anywhere and attempted CREATE EXTENSION IF NOT EXISTS <ext> SCHEMA <shared> on the bootstrap connection. PostgreSQL raises an error when the connecting role lacks superuser/CREATEDB-appropriate privileges or the extension's control file is missing. The message explicitly says a privileged user must run the CREATE EXTENSION once because the app intentionally supports pre-installation by an administrator.

Source

Thrown at backend/pkg/database/tenant.go:117

// ensureSharedExtension guarantees that ext exists in sharedSchema and is
// therefore reachable from every tenant's search_path. It checks before
// creating so that a database whose extensions were pre-installed by an
// administrator (or by convention — see DATABASE_EXTENSIONS_SCHEMA in
// backend/docs/config.md) works without the application needing CREATE
// privileges.
func ensureSharedExtension(ctx context.Context, conn *sql.Conn, ext, sharedSchema string) error {
	schema, err := extensionSchema(ctx, conn, ext)
	switch {
	case err != nil:
		return err

	case schema == "":
		// Not installed yet — create it explicitly in the shared schema.
		if _, err := conn.ExecContext(ctx, fmt.Sprintf(
			"CREATE EXTENSION IF NOT EXISTS %s SCHEMA %s",
			pq.QuoteIdentifier(ext), pq.QuoteIdentifier(sharedSchema),
		)); err != nil {
			return fmt.Errorf(
				"failed to create extension %q in schema %q (a privileged user must run "+
					"CREATE EXTENSION %s SCHEMA %s once): %w",
				ext, sharedSchema, ext, sharedSchema, err,
			)
		}
		return nil

	case schema != sharedSchema:
		// Installed, but somewhere this tenant's search_path will not reach. Fail
		// with an actionable message rather than letting migrations die on a
		// confusing "type does not exist".
		return fmt.Errorf(
			"extension %q is installed in schema %q, but multi-tenant mode requires it in %q "+
				"so every tenant can reach it; either run ALTER EXTENSION %s SET SCHEMA %s, "+
				"or set DATABASE_EXTENSIONS_SCHEMA=%s to match where it already lives",
			ext, schema, sharedSchema, ext, sharedSchema, schema,
		)

View on GitHub (pinned to ea665308ba)

Solutions

1. Install the extension into the image: use the pgvector/pgvector image or apt-get install postgresql-16-pgvector / pg_trgm package, then restart.
2. Run once as a superuser: CREATE EXTENSION vector SCHEMA public; CREATE EXTENSION pg_trgm SCHEMA public; (use your DATABASE_EXTENSIONS_SCHEMA).
3. On managed Postgres, enable pgvector/pg_trgm for the instance via the provider's supported-extensions list and use a role allowed to create it.
4. If extensions are pre-installed by ops, just make sure they exist in the shared schema so the app skips creation (schema != "" path).

Example fix

// before (app role)
CREATE EXTENSION IF NOT EXISTS vector SCHEMA public; -- ERROR: permission denied to create extension
// after (run once as postgres superuser)
CREATE EXTENSION IF NOT EXISTS vector SCHEMA public;
CREATE EXTENSION IF NOT EXISTS pg_trgm SCHEMA public;

// verify extension availability before app start
psql "$DATABASE_URL" -c "SELECT name FROM pg_available_extensions WHERE name IN ('vector','pg_trgm');"
// empty result means the image lacks the extension packages

if err := EnsureTenantSchema(ctx, cfg); err != nil {
    if strings.Contains(err.Error(), "failed to create extension") {
        return fmt.Errorf("install pgvector/pg_trgm in the image and run CREATE EXTENSION once as superuser: %w", err)
    }
    return err
}

When it happens

Trigger: TENANT_ID is set, extensionSchema() returns "" for "vector" or "pg_trgm", and the CREATE EXTENSION fails: role is not superuser and lacks the extension's creation rights, or the extension .control/.so files are not installed in the PostgreSQL image (e.g. plain postgres image without pgvector).

Common situations: Using the stock postgres Docker image instead of pgvector/pgvector:pg16, so pgvector is not available at all; running PentAGI with a non-superuser application role; upgrading the DB image and losing the pgvector package; managed databases (RDS/Cloud SQL) where CREATE EXTENSION requires specific whitelisting.

Related errors

• extension %q is installed in schema %q, but multi-tenant mod
• knowledge: list by flow: %w
• knowledge: list all: %w
• knowledge: list by flow (user): %w
• failed to create schema %q: %w

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/4ed483a2ab5f3f64. Report an issue: GitHub.