googleapis/mcp-toolbox · error

failed to initialize AlloyDB source in read-only mode: 'allo

Error message

failed to initialize AlloyDB source in read-only mode: 'alloydb_session_read_only' is not supported on this instance version. See documentation for details: https://mcp-toolbox.dev/integrations/alloydb/source/#reference: %w

What it means

When a read-only alloydbpg source pings the database, it sets the alloydb_session_read_only configuration parameter. On older AlloyDB instance versions this parameter doesn't exist, and Postgres replies 'unrecognized configuration parameter'. The source detects this specific failure during pool.Ping and returns this descriptive error, closing the pool first.

Source

Thrown at internal/sources/alloydbpg/alloydb_pg.go:83

}

func (r Config) SourceConfigType() string {
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	pool, err := initAlloyDBPgConnectionPool(ctx, tracer, r.Name, r.Project, r.Region, r.Cluster, r.Instance, r.IPType.String(), r.User, r.Password, r.Database, r.ReadOnly)
	if err != nil {
		return nil, fmt.Errorf("unable to create pool: %w", err)
	}

	err = pool.Ping(ctx)
	if err != nil {
		pool.Close()
		if r.ReadOnly &&
			strings.Contains(err.Error(), "unrecognized configuration parameter") &&
			strings.Contains(err.Error(), "alloydb_session_read_only") {
			return nil, fmt.Errorf("failed to initialize AlloyDB source in read-only mode: 'alloydb_session_read_only' is not supported on this instance version. See documentation for details: https://mcp-toolbox.dev/integrations/alloydb/source/#reference: %w", err)
		}
		return nil, fmt.Errorf("unable to connect successfully: %w", err)
	}

	s := &Source{
		Config: r,
		Pool:   pool,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	Pool *pgxpool.Pool
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Upgrade the AlloyDB instance to a version supporting alloydb_session_read_only.
2. Set readOnly: false in the source config until the instance is upgraded.
3. Verify instance version in the Google Cloud console or via `gcloud alloydb instances describe`.
4. Check the linked docs (mcp-toolbox.dev alloydb source reference) for supported versions.

Example fix

// before
sources:
  alloydb-src:
    kind: alloydb-postgres
    readOnly: true   # unsupported on this instance version
// after
sources:
  alloydb-src:
    kind: alloydb-postgres
    readOnly: false  # or upgrade the AlloyDB instance first

# Confirm the instance version supports alloydb_session_read_only before enabling readOnly
gcloud alloydb instances describe INSTANCE --cluster=CLUSTER --region=REGION --format="value(name,activationPolicy)"
# test the parameter directly:
psql "..." -c "SET alloydb_session_read_only = on;"

src, err := cfg.Initialize(ctx, tracer)
if err != nil && strings.Contains(err.Error(), "alloydb_session_read_only") {
    // fall back to a non-read-only source or schedule an instance upgrade
    log.Warn("readOnly unsupported on this instance version; disable readOnly or upgrade")
}

When it happens

Trigger: Configuring `readOnly: true` on an alloydb-postgres source whose target AlloyDB instance runs a version that predates support for the alloydb_session_read_only parameter; the Ping fails with 'unrecognized configuration parameter: alloydb_session_read_only'.

Common situations: Connecting to an AlloyDB instance that hasn't been upgraded to a version supporting session-level read-only enforcement, often after enabling readOnly in a toolbox config copied from docs.

Related errors

• invalid ipType %s
• password is provided without a username. Please provide both
• unable to initialize logger: %w
• invalid log level
• unable to initialize tool %q: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/972423430ea4168e. Report an issue: GitHub.