jackc/pgx · error

config must be created by ParseConfig

Error message

config must be created by ParseConfig

What it means

pgx's internal connect rejects a *ConnConfig that was not produced by ParseConfig: hand-constructed configs lack parsed runtime state (fallbacks, defaults, sanitized settings), so the guard forces construction through the supported path before any network work begins.

Solutions

1. Build the config with pgx.ParseConfig (or ParseConfigWithOptions) and then mutate fields
2. Clone an existing parsed ConnConfig instead of constructing one literally

When it happens

Trigger: Thrown at conn.go:255 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/5f8c4d3d151f501a. Report an issue: GitHub.

Appendix: source

Thrown at conn.go:255

//     The maximum size of the description cache used when executing a query with "cache_describe" query exec mode.
//     Default: 512.
func ParseConfig(connString string) (*ConnConfig, error) {
	return ParseConfigWithOptions(connString, ParseConfigOptions{})
}

// connect connects to a database. connect takes ownership of config. The caller must not use or access it again.
func connect(ctx context.Context, config *ConnConfig) (c *Conn, err error) {
	if connectTracer, ok := config.Tracer.(ConnectTracer); ok {
		ctx = connectTracer.TraceConnectStart(ctx, TraceConnectStartData{ConnConfig: config})
		defer func() {
			connectTracer.TraceConnectEnd(ctx, TraceConnectEndData{Conn: c, Err: err})
		}()
	}

	// Default values are set in ParseConfig. Enforce initial creation by ParseConfig rather than setting defaults from
	// zero values.
	if !config.createdByParseConfig {
		panic("config must be created by ParseConfig")
	}

	c = &Conn{
		config:      config,
		typeMap:     pgtype.NewMap(),
		queryTracer: config.Tracer,
	}

	if t, ok := c.queryTracer.(BatchTracer); ok {
		c.batchTracer = t
	}
	if t, ok := c.queryTracer.(CopyFromTracer); ok {
		c.copyFromTracer = t
	}
	if t, ok := c.queryTracer.(PrepareTracer); ok {
		c.prepareTracer = t
	}

View on GitHub (pinned to ec1a0befd2)