go-sql-driver/mysql · error

invalid DSN: did you forget to escape a param value?

Error message

invalid DSN: did you forget to escape a param value?

What it means

Error "invalid DSN: did you forget to escape a param value?" thrown in go-sql-driver/mysql.

Solutions

1. URL-escape special characters in DSN parameter values, e.g. replace '/' with %2F and '&' with %26 in passwords or other values.
2. Use url.QueryEscape (or the driver's Config.FormatDSN) to build the DSN instead of string concatenation.

Example fix

cfg := mysql.NewConfig()
cfg.User = "user"
cfg.Passwd = "p@ss/word" // FormatDSN escapes it automatically
cfg.Net = "tcp"
cfg.Addr = "127.0.0.1:3306"
cfg.DBName = "mydb"
dsn := cfg.FormatDSN()

When it happens

Trigger: Parsing the DSN fails because a parameter value contains a reserved character (such as '/' or '?') that was not URL-escaped, so the parser misinterprets the DSN structure.

Common situations: Occurs when passwords or other DSN values contain special characters like '@', '/', ':', or '?'. Escape the value with url.QueryEscape or url.PathEscape, e.g. user:pa%40ss@tcp(host)/db.

AI-assisted analysis of go-sql-driver/mysql@03d76c7e07 (2026-08-07). Data as JSON: /api/errors/c3132b0f75cbad61. Report an issue: GitHub.

Appendix: source

Thrown at dsn.go:29

import (
	"bytes"
	"context"
	"crypto/rsa"
	"crypto/tls"
	"errors"
	"fmt"
	"maps"
	"math/big"
	"net"
	"net/url"
	"sort"
	"strconv"
	"strings"
	"time"
)

var (
	errInvalidDSNUnescaped       = errors.New("invalid DSN: did you forget to escape a param value?")
	errInvalidDSNAddr            = errors.New("invalid DSN: network address not terminated (missing closing brace)")
	errInvalidDSNNoSlash         = errors.New("invalid DSN: missing the slash separating the database name")
	errInvalidDSNUnsafeCollation = errors.New("invalid DSN: interpolateParams can not be used with unsafe collations")
)

// Config is a configuration parsed from a DSN string.
// If a new Config is created instead of being parsed from a DSN string,
// the NewConfig function should be used, which sets default values.
type Config struct {
	// non boolean fields

	User                 string            // Username
	Passwd               string            // Password (requires User)
	Net                  string            // Network (e.g. "tcp", "tcp6", "unix". default: "tcp")
	Addr                 string            // Address (default: "127.0.0.1:3306" for "tcp" and "/tmp/mysql.sock" for "unix")
	DBName               string            // Database name
	Params               map[string]string // Connection parameters
	ConnectionAttributes string            // Connection Attributes, comma-delimited string of user-defined "key:value" pairs

View on GitHub (pinned to 03d76c7e07)