golang-migrate/migrate · error

failed to parse consistency "%s": %v

Error message

failed to parse consistency "%s": %v

What it means

In the Cassandra driver, parseConsistency wraps gocql.ParseConsistency. ParseConsistency panics for an unrecognized consistency string; the deferred recover converts that panic into an error. If the recovered value is not an error, the string "failed to parse consistency \"%s\": %v" is produced, embedding the offending input and the panic value.

Source

Thrown at database/cassandra/cassandra.go:339

	err = c.session.Query(fmt.Sprintf("CREATE TABLE IF NOT EXISTS %s (version bigint, dirty boolean, PRIMARY KEY(version))", c.config.MigrationsTable)).Exec()
	if err != nil {
		return err
	}
	if _, _, err = c.Version(); err != nil {
		return err
	}
	return nil
}

// ParseConsistency wraps gocql.ParseConsistency
// to return an error instead of a panicking.
func parseConsistency(consistencyStr string) (consistency gocql.Consistency, err error) {
	defer func() {
		if r := recover(); r != nil {
			var ok bool
			err, ok = r.(error)
			if !ok {
				err = fmt.Errorf("failed to parse consistency \"%s\": %v", consistencyStr, r)
			}
		}
	}()
	consistency = gocql.ParseConsistency(consistencyStr)

	return consistency, nil
}

View on GitHub (pinned to 01a9643f14)

Solutions

1. Correct the consistency string to a valid gocql level: any, one, two, three, quorum, all, local_quorum, each_quorum, local_one.
2. Check the x-consistency query parameter in the Cassandra URL for typos and exact spelling.
3. Validate the consistency string against gocql.ParseConsistency in a recover-safe wrapper before building the cluster config.

Example fix

// before
dsn := "cassandra://host:9042/keyspace?x-consistency=quorom"
// after
dsn := "cassandra://host:9042/keyspace?x-consistency=quorum"

validConsistencies := map[string]bool{
    "any": true, "one": true, "two": true, "three": true, "quorum": true,
    "all": true, "local_quorum": true, "each_quorum": true, "local_one": true,
}
if !validConsistencies[strings.ToLower(consistency)] {
    return fmt.Errorf("invalid consistency %q", consistency)
}

if err != nil && strings.Contains(err.Error(), "failed to parse consistency") {
    return fmt.Errorf("check the x-consistency parameter in your Cassandra URL: %w", err)
}

When it happens

Trigger: Passing an invalid x-consistency query parameter or Config consistency value (e.g. "quorom" misspelling, "foo") that gocql.ParseConsistency panics on with a non-error panic value.

Common situations: Typo in the consistency level in the Cassandra DSN query string; case/spacing mistakes; using a consistency level from a different driver's naming convention.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• no config
• no keyspace provided
• unable to parse option x-migrations-table-quoted: %w
• unable to parse option x-multi-statement: %w
• unable to parse option x-migrations-table-quoted: %w

AI-assisted analysis of golang-migrate/migrate@01a9643f14 (2026-09-02). Data as JSON: /api/errors/3c7ac718344b92cf. Report an issue: GitHub.