vitessio/vitess · error

values %v for column %v does not map to keyspace ids

Error message

values %v for column %v does not map to keyspace ids

What it means

When inserting into a table with unowned vindexes (e.g. lookup vindexes the application must populate), processUnowned verifies that the supplied column values actually map to keyspace ids. If verification shows the values do not map (mismatchVindexKeys set), the insert fails with this error so inconsistent vindex state is not created.

Source

Thrown at go/vt/vtgate/engine/insert_common.go:338

		}

		var mismatchVindexKeys []sqltypes.Row
		for i, v := range verified {
			rowNum := verifyIndexes[i]
			if !v {
				if !ic.Ignore {
					mismatchVindexKeys = append(mismatchVindexKeys, vindexColumnsKeys[rowNum])
					continue
				}

				// Skip the whole row if this is a `INSERT IGNORE` or `INSERT ... ON DUPLICATE KEY ...` statement
				// but the keyspace ids didn't match.
				ksids[verifyIndexes[i]] = nil
			}
		}

		if mismatchVindexKeys != nil {
			return fmt.Errorf("values %v for column %v does not map to keyspace ids", mismatchVindexKeys, colVindex.Columns)
		}
	}

	return nil
}

// processGenerateFromSelect generates new values using a sequence if necessary.
// If no value was generated, it returns 0. Values are generated only
// for cases where none are supplied.
func (ic *InsertCommon) processGenerateFromSelect(
	ctx context.Context,
	vcursor VCursor,
	loggingPrimitive Primitive,
	rows []sqltypes.Row,
) (insertID int64, err error) {
	if ic.Generate == nil {
		return 0, nil
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Rebuild/repair the lookup vindex table so its entries point to the correct keyspace ids
2. Verify the inserted values are consistent with the existing vindex data before inserting
3. If the value legitimately belongs elsewhere, delete the stale lookup entry first

// before insert, confirm the unowned vindex value maps consistently
ksids, err := vindex.Map(cursor, vindexParams, []string{val})
if err != nil || len(ksids) == 0 || hasNilKsid(ksids) {
    return fmt.Errorf("value %v does not map to keyspace ids", val)
}

if err := insert(row); err != nil && strings.Contains(err.Error(), "does not map to keyspace ids") {
    // repair lookup vindex entries for the offending value, then retry
}

When it happens

Trigger: INSERT (or ON DUPLICATE KEY UPDATE / REPLACE via processVindexes -> processUnowned) where a value for an unowned vindex column exists in the lookup table but points to different keyspace ids, or cannot be verified to map consistently.

Common situations: Stale or inconsistent lookup-vindex tables after resharding; application-inserted lookup rows pointing at wrong shards; inserting duplicate values that already map elsewhere.

Related errors

• one or two tables must be specified
• at least one table must be specified
• vindex is in write-only mode
• vindex has no owner
• Binary.ReverseMap: keyspaceId is nil

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/9264d993c1c48b24. Report an issue: GitHub.