What causes "keyspace not found" in vitessio/vitess?

Verify the keyspace exists: vtctldclient GetKeyspace .

vitessio/vitess · error · ErrKeyspaceNotFound

keyspace not found

Error message

keyspace not found

What it means

ErrKeyspaceNotFound is the sentinel error returned by ReadKeyspace when the vitess keyspace record is absent from the vtorc/topo-backed database. Callers compare with errors.Is to detect a missing keyspace versus a real failure.

Source

Thrown at go/vt/vtorc/inst/keyspace_dao.go:31

See the License for the specific language governing permissions and
limitations under the License.
*/

package inst

import (
	"errors"

	"vitess.io/vitess/go/vt/external/golib/sqlutils"
	topodatapb "vitess.io/vitess/go/vt/proto/topodata"
	vtorcdatapb "vitess.io/vitess/go/vt/proto/vtorcdata"
	"vitess.io/vitess/go/vt/topo"
	"vitess.io/vitess/go/vt/vtctl/reparentutil/policy"
	"vitess.io/vitess/go/vt/vtorc/db"
)

// ErrKeyspaceNotFound is a fixed error message used when a keyspace is not found in the database.
var ErrKeyspaceNotFound = errors.New("keyspace not found")

// ReadKeyspace reads the vitess keyspace record.
func ReadKeyspace(keyspaceName string) (*topo.KeyspaceInfo, error) {
	if err := topo.ValidateKeyspaceName(keyspaceName); err != nil {
		return nil, err
	}

	query := `select
			keyspace_type,
			durability_policy,
			disable_emergency_reparent
		from
			vitess_keyspace
		where
			keyspace = ?`
	args := sqlutils.Args(keyspaceName)

	keyspace := &topo.KeyspaceInfo{

View on GitHub (pinned to 01a25a7d17)

Solutions

Verify the keyspace exists: vtctldclient GetKeyspace <name>.
Fix the keyspace name in vtorc configuration/flags.
Create the keyspace via vtctldclient CreateKeyspace if it should exist.

Example fix

// before
ks, err := inst.ReadKeyspace(ksName)
if err != nil { return err }
// after
ks, err := inst.ReadKeyspace(ksName)
if errors.Is(err, inst.ErrKeyspaceNotFound) {
    return fmt.Errorf("keyspace %s does not exist; check spelling or create it", ksName)
} else if err != nil { return err }

Defensive patterns

Strategy: validation

Validate before calling

if keyspaceName == "" {
    return errors.New("keyspace name is required")
}
// optionally verify existence first via topo server read

Try / catch

ks, err := inst.ReadKeyspace(ksName)
if errors.Is(err, inst.ErrKeyspaceNotFound) {
    return handleMissingKeyspace(ksName) // create it or fix config
} else if err != nil { return err }

Prevention

Verify keyspace names in vtorc flags/config against vtctldclient GetKeyspace.
Create keyspaces before pointing vtorc at them.
Use errors.Is against the sentinel instead of string matching.

When it happens

Trigger: ReadKeyspace(keyspaceName) when no row for that keyspace exists — the keyspace was never created, was deleted, or the name is misspelled.

Common situations: Typo in --clusters_to_watch or keyspace configuration; keyspace dropped by vtctl while vtorc still references it; running vtorc against an empty/new cluster before keyspace creation.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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