googleapis/mcp-toolbox · error

failed to sample relationship type %q: %w

Error message

failed to sample relationship type %q: %w

What it means

Thrown when the per-relationship-type sampling query ('MATCH (a)-[r:`<type>`]->(b) RETURN ... LIMIT <SampleSize>') fails inside extractRelationships. The sampling query fetches start/end labels and sample edges to derive connectivity patterns and property shapes. Any driver or query error is wrapped with the relationship type name.

Source

Thrown at internal/tools/falkordb/falkordbschema/falkordbschema.go:344

func (t Tool) extractRelationships(ctx context.Context, source compatibleSource) ([]types.Relationship, error) {
	typesResult, err := runReadQuery(ctx, source, "CALL db.relationshipTypes()")
	if err != nil {
		return nil, fmt.Errorf("failed to list relationship types: %w", err)
	}

	var relationships []types.Relationship
	for _, relType := range helpers.FirstColumnStrings(typesResult) {
		escaped := escapeIdentifier(relType)

		countResult, err := runReadQuery(ctx, source, fmt.Sprintf("MATCH ()-[r:`%s`]->() RETURN count(r) AS count", escaped))
		if err != nil {
			return nil, fmt.Errorf("failed to count relationship type %q: %w", relType, err)
		}

		sampleResult, err := runReadQuery(ctx, source, fmt.Sprintf(
			"MATCH (a)-[r:`%s`]->(b) RETURN labels(a) AS startLabels, labels(b) AS endLabels, r LIMIT %d", escaped, t.Cfg.SampleSize))
		if err != nil {
			return nil, fmt.Errorf("failed to sample relationship type %q: %w", relType, err)
		}

		accumulator := make(map[string]map[string]bool)
		connectivity := make(map[types.RelConnectivityInfo]int64)
		for _, row := range helpers.Rows(sampleResult) {
			if edge, ok := row["r"].(map[string]any); ok {
				if properties, ok := edge["properties"].(map[string]any); ok {
					helpers.MergeProperties(accumulator, properties)
				}
			}
			pattern := types.RelConnectivityInfo{
				StartNode: firstString(row["startLabels"]),
				EndNode:   firstString(row["endLabels"]),
			}
			connectivity[pattern]++
		}

		relationship := types.Relationship{

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Check the wrapped cause for the driver-level error.
2. Set Cfg.SampleSize to a small positive integer (e.g., 5-50).
3. Verify server health and connection stability.
4. Re-run the schema extraction after fixing the underlying issue.

Example fix

// before
sampleSize: 0
// after
sampleSize: 20

// Validate SampleSize before running extraction
if t.Cfg.SampleSize <= 0 {
    return errors.New("sampleSize must be a positive integer")
}

func validSampleSize(n int) bool { return n > 0 && n <= 1000 }

rels, err := tool.ExtractRelationships(ctx, src)
if err != nil {
    if strings.Contains(err.Error(), "failed to sample relationship type") {
        // reduce SampleSize or skip sampling and degrade to counts only
    }
    return err
}

When it happens

Trigger: runReadQuery fails on the sample query: connection failure, auth error, query timeout, LIMIT value from Cfg.SampleSize invalid (e.g., 0 or negative in some backends), or server error traversing the relationship type.

Common situations: SampleSize misconfigured to an invalid value; long-running traversal timeouts on dense relationship types; transient network issues during multi-query schema extraction.

Related errors

• failed to list relationship types: %w
• failed to count relationship type %q: %w
• tls.insecureSkipVerify is set on source %q but tls.enabled i
• unable to get logger from ctx: %s
• unable to create client: %w

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