googleapis/mcp-toolbox · error

failed to get instance: %w

Error message

failed to get instance: %w

What it means

This error wraps a failure from the Cloud Bigtable admin client's InstanceAdmin.InstanceInfo call when fetching metadata for a Bigtable instance. It means the instance could not be looked up — usually because it does not exist, the caller lacks permission, or the admin client's connection failed. The underlying gRPC/API error is preserved via %w.

Source

Thrown at internal/sources/bigtable/admin_wrappers.go:29

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package bigtable

import (
	"context"
	"errors"
	"fmt"
	"time"

	"cloud.google.com/go/bigtable"
)

func (s *Source) GetInstance(ctx context.Context, instanceId string) (any, error) {
	instance, err := s.InstanceAdmin.InstanceInfo(ctx, instanceId)
	if err != nil {
		return nil, fmt.Errorf("failed to get instance: %w", err)
	}
	return instance, nil
}

func (s *Source) CreateInstance(ctx context.Context, instanceId, displayName, clusterId, zone string, numNodes int32) (any, error) {
	conf := &bigtable.InstanceConf{
		InstanceId:  instanceId,
		DisplayName: displayName,
		ClusterId:   clusterId,
		Zone:        zone,
		NumNodes:    numNodes,
	}
	err := s.InstanceAdmin.CreateInstance(ctx, conf)
	if err != nil {
		return nil, fmt.Errorf("failed to create instance: %w", err)
	}
	return map[string]string{"status": "instance created successfully"}, nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify the instanceId exactly matches an existing instance: `gcloud bigtable instances list`.
2. Confirm credentials point at the correct project and the principal has bigtable.instances.get (roles/bigtable.viewer or admin).
3. Check network reachability to bigtableadmin.googleapis.com (proxy/firewall).
4. Re-create the instance if it was deleted.
5. Inspect the wrapped inner error for a 404 vs. 403 vs. timeout to target the right fix.

Example fix

// before
instance, err := s.InstanceAdmin.InstanceInfo(ctx, instanceId)
if err != nil {
    return nil, fmt.Errorf("failed to get instance: %w", err)
}
// after
instance, err := s.InstanceAdmin.InstanceInfo(ctx, instanceId)
if err != nil {
    if st, ok := status.FromError(err); ok && st.Code() == codes.NotFound {
        return nil, fmt.Errorf("instance %q not found in project; check the instance ID: %w", instanceId, err)
    }
    return nil, fmt.Errorf("failed to get instance %q: %w", instanceId, err)
}

adminClient, err := bigtable.NewAdminClient(ctx, project, instanceId)
if err != nil {
    return fmt.Errorf("cannot reach project %q / instance %q: %w", project, instanceId, err)
}
adminClient.Close()

func isNotFound(err error) bool {
    st, ok := status.FromError(err)
    return ok && st.Code() == codes.NotFound
}

inst, err := src.GetInstance(ctx, id)
if err != nil {
    var st *status.Status
    if errors.As(err, &st) && st.Code() == codes.NotFound {
        return nil, fmt.Errorf("instance %q not found; verify the instance ID", id)
    }
    if errors.As(err, &st) && st.Code() == codes.PermissionDenied {
        return nil, fmt.Errorf("missing bigtable.instances.get permission: %w", err)
    }
    return nil, err
}

When it happens

Trigger: Calling GetInstance(ctx, instanceId) where instanceId does not exist in the project, the service account lacks bigtable.instances.get (or bigtable.admin role), the instance name is misspelled, or the underlying gRPC connection to bigtableadmin.googleapis.com fails.

Common situations: Typo in instance ID passed by an LLM/tool caller, tool run with credentials from a different project than the instance, IAM principal missing Bigtable Admin/Viewer roles, or instances deleted/renamed between listing and fetch.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• failed to update instance: %w
• failed to update cluster: %w
• failed to delete cluster: %w
• failed to get table: %w
• failed to create table: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/ddb81e1fb45b4000. Report an issue: GitHub.