bytebase/bytebase · error

failed to get instance %s

Error message

failed to get instance %s

What it means

After successfully parsing the target, resolveDatabaseTarget loads the instance with stores.GetInstanceByResourceID. A database error occurred during that lookup (connection failure, query error) and is wrapped with this message naming the instance ID. Note this is distinct from the not-found case, which returns its own error.

Source

Thrown at backend/runner/plancheck/target.go:21

import (
	"context"

	"github.com/pkg/errors"

	"github.com/bytebase/bytebase/backend/common"
	"github.com/bytebase/bytebase/backend/store"
)

// resolveDatabaseTarget resolves a workspace- or project-scoped database resource name.
func resolveDatabaseTarget(ctx context.Context, stores *store.Store, target string) (*store.InstanceMessage, *store.DatabaseMessage, error) {
	projectID, instanceID, databaseName, err := common.GetDatabaseResourceName(target)
	if err != nil {
		return nil, nil, errors.Wrapf(err, "failed to parse target %s", target)
	}

	instance, err := stores.GetInstanceByResourceID(ctx, instanceID)
	if err != nil {
		return nil, nil, errors.Wrapf(err, "failed to get instance %s", instanceID)
	}
	if instance == nil {
		return nil, nil, errors.Errorf("instance %s not found", instanceID)
	}
	if instance.Deleted {
		return nil, nil, errors.Errorf("instance %s has been deleted", instanceID)
	}
	if (projectID == nil) != (instance.ProjectID == nil) ||
		projectID != nil && *instance.ProjectID != *projectID {
		if projectID == nil {
			return nil, nil, errors.Errorf("project instance %q must be addressed through its project", instanceID)
		}
		return nil, nil, errors.Errorf("instance %q does not belong to project %q", instanceID, *projectID)
	}

	database, err := stores.GetDatabase(ctx, &store.FindDatabaseMessage{InstanceID: &instance.ResourceID, DatabaseName: &databaseName})
	if err != nil {
		return nil, nil, errors.Wrapf(err, "failed to get database %q", databaseName)

View on GitHub (pinned to 1870550677)

Solutions

1. Check the wrapped inner error for the store/DB failure cause
2. Verify the metadata database connectivity (PG_URL) and that the Bytebase store can query
3. Retry the operation if the failure was transient (connection reset/pool timeout)

Example fix

// before
instance, err := stores.GetInstanceByResourceID(ctx, instanceID)
if err != nil {
	return nil, nil, errors.Wrapf(err, "failed to get instance %s", instanceID)
}
// after
instance, err := stores.GetInstanceByResourceID(ctx, instanceID)
if err != nil {
	if isTransientDBError(err) {
		// retry once before surfacing
		instance, err = stores.GetInstanceByResourceID(ctx, instanceID)
	}
	if err != nil {
		return nil, nil, errors.Wrapf(err, "failed to get instance %s", instanceID)
	}
}

if instanceID == "" {
	return errors.New("instanceID parsed from target is empty")
}

var nerr net.Error
if errors.As(err, &nerr) && nerr.Timeout() {
	// transient: retry with backoff
} else if isConnectionError(err) {
	// check metadata DB health before retrying
}

When it happens

Trigger: GetInstanceByResourceID returns a non-nil error: the metadata database is unreachable, the query fails, or a store-level constraint breaks while fetching the instance row for instanceID.

Common situations: Metadata Postgres down or misconfigured (bad PG_URL); transient connection pool exhaustion; corrupted store state triggering a query error during the instance read.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• no update field specified
• no update field provided
• no fields to update
• no fields to update
• failed to find instance

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/54542decbe93d15e. Report an issue: GitHub.