jackc/pgx · error

unknown QueryExecMode

Error message

unknown QueryExecMode: %v

What it means

Conn.Exec reached the mode switch with a QueryExecMode value that matches none of the five known modes. This can only happen if the mode integer was constructed abnormally (e.g. an undefined or custom-cast value), since ParseConfig validates string configuration earlier.

Solutions

1. Use only QueryExecMode constants defined by pgx
2. Check for a stale or incompatible pgx version where mode constants were type-cast from raw integers
3. Audit custom code that casts arbitrary integers to QueryExecMode

When it happens

Trigger: Thrown at conn.go:580 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/e4a1ee559b37f287. Report an issue: GitHub.

Appendix: source

Thrown at conn.go:580

			if err != nil {
				return pgconn.CommandTag{}, err
			}
			c.descriptionCache.Put(sd)
		}

		return c.execParams(ctx, sd, arguments)
	case QueryExecModeDescribeExec:
		sd, err := c.Prepare(ctx, "", sql)
		if err != nil {
			return pgconn.CommandTag{}, err
		}
		return c.execPrepared(ctx, sd, arguments)
	case QueryExecModeExec:
		return c.execSQLParams(ctx, sql, arguments)
	case QueryExecModeSimpleProtocol:
		return c.execSimpleProtocol(ctx, sql, arguments)
	default:
		return pgconn.CommandTag{}, fmt.Errorf("unknown QueryExecMode: %v", mode)
	}
}

func (c *Conn) execSimpleProtocol(ctx context.Context, sql string, arguments []any) (commandTag pgconn.CommandTag, err error) {
	if len(arguments) > 0 {
		sql, err = c.sanitizeForSimpleQuery(sql, arguments...)
		if err != nil {
			return pgconn.CommandTag{}, err
		}
	}

	mrr := c.pgConn.Exec(ctx, sql)
	for mrr.NextResult() {
		commandTag, _ = mrr.ResultReader().Close()
	}
	err = mrr.Close()
	return commandTag, err
}

View on GitHub (pinned to ec1a0befd2)