What causes "Unknown option in similar_to: %q" in dgraph-io/dgraph?

Use only supported keys: 'ef' and 'distance_threshold'.

Unknown option in similar_to: %q

Error message

Unknown option in similar_to: %q

What it means

The similar_to option parser accepts only the keys 'ef' and 'distance_threshold'. Any other key reaches the default branch of the switch and produces this error, naming the offending key. This prevents silently ignoring misspelled options.

Source

Thrown at worker/task.go:2818

			if perr != nil {
				return errors.Errorf("Invalid value for 'ef' in similar_to: %q", v)
			}
			if n <= 0 {
				return errors.Errorf("Value for 'ef' must be positive, got: %d", n)
			}
			fc.vsEfOverride = int(n)
		case "distance_threshold":
			f, perr := strconv.ParseFloat(v, 64)
			if perr != nil {
				return errors.Errorf("Invalid value for 'distance_threshold' in similar_to: %q", v)
			}
			if f < 0 {
				return errors.Errorf("Value for 'distance_threshold' must be non-negative, got: %v", f)
			}
			fc.vsDistanceThreshold = new(float64)
			*fc.vsDistanceThreshold = f
		default:
			return errors.Errorf("Unknown option in similar_to: %q", k)
		}
	}
	return nil
}

View on GitHub (pinned to 759e242be6)

Solutions

Use only supported keys: 'ef' and 'distance_threshold'.
Fix the typo in the option key in the failing query.
Check the Dgraph version's documented similar_to options if migrating from another version.

Example fix

// before
"vec; ef_s: 100"
// after
"vec; ef: 100"

Defensive patterns

Strategy: validation

Validate before calling

allowed := map[string]bool{"ef": true, "distance_threshold": true}
for k := range myOptions {
    if !allowed[k] { return fmt.Errorf("unsupported similar_to option: %s", k) }
}

Try / catch

if err := runQuery(ctx); err != nil && strings.Contains(err.Error(), "Unknown option in similar_to") {
    return fmt.Errorf("check similar_to keys (only ef, distance_threshold allowed): %w", err)
}

Prevention

Keep a whitelist of supported similar_to keys in your query builder.
Check the Dgraph docs for the current option set when upgrading versions.
Avoid copying option syntax from other vector search engines.

When it happens

Trigger: similar_to option string with a typo'd or unsupported key: 'similar_to: "vec; efs: 100"', 'ef-s: 10', 'k: 5', or capitalization variants if any slip through. The key is matched after trimming trailing colons, so 'ef:' keys still match, but 'EF' style variants would not if case differs.

Common situations: Typos like 'ef_s' or 'distanceThreshhold'; copying options from a different search engine's syntax (e.g. 'k:' from kNN APIs); older query syntax that used a since-removed option name after a version upgrade.

Related errors

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/89828647fd637699. Report an issue: GitHub.