gastownhall/beads · error

invalid pull filter: %w

Error message

invalid pull filter: %w

What it means

Wraps a failure from filters.Validate() on the pull filters built by buildADOPullFilters for `bd ado sync`. Pull filters (from CLI flags falling back to config values, e.g. state/area/work-item-type constraints) are validated before being handed to the tracker; an invalid combination or value aborts the sync with this message.

Source

Thrown at cmd/bd/ado.go:537

	out := cmd.OutOrStdout()
	ctx := context.Background()

	// Create and initialize the ADO tracker
	at := &ado.Tracker{}
	cliProjects, _ := cmd.Flags().GetStringSlice("project")
	if len(cliProjects) > 0 {
		at.SetProjects(tracker.DeduplicateStrings(cliProjects))
	}
	if err := at.Init(ctx, store); err != nil {
		return fmt.Errorf("initializing Azure DevOps tracker: %w", err)
	}

	// Build pull filters from CLI flags, falling back to config values.
	filters := buildADOPullFilters(ctx, cmd)
	if filters != nil {
		if err := filters.Validate(); err != nil {
			return fmt.Errorf("invalid pull filter: %w", err)
		}
		at.SetFilters(filters)
	}

	// Create the sync engine
	engine := tracker.NewEngine(at, store, actor)
	var warnings []string
	if !jsonOutput {
		engine.OnMessage = func(msg string) { _, _ = fmt.Fprintln(out, "  "+msg) }
	}
	engine.OnWarning = func(msg string) {
		warnings = append(warnings, msg)
		_, _ = fmt.Fprintf(os.Stderr, "Warning: %s\n", msg)
	}

	// Set up ADO-specific pull hooks (with bootstrap matching and no-create support)
	var bootstrapMatched int
	engine.PullHooks = buildADOPullHooks(ctx, at, adoBootstrapMatch, adoNoCreate, &bootstrapMatched, engine.OnWarning)

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause after 'invalid pull filter:' — it names the offending filter field/value.
2. Remove or correct the invalid filter flag on the bd ado sync invocation.
3. Check the ado pull-filter entries in `bd config` values against names in Azure DevOps (states, area paths, types).
4. If the filter came from config, fix or delete the entry, then re-run sync.
5. Verify filter semantics against `bd ado sync --help` (which flags combine).

Example fix

// before
bd ado sync --state actv

// after
bd ado sync --state active

func validatePullFilter(f pullFilter) error {
	if f.State != "" && !slices.Contains(validStates, f.State) {
		return fmt.Errorf("unknown state %q", f.State)
	}
	if f.Type != "" && !slices.Contains(validTypes, f.Type) {
		return fmt.Errorf("unknown type %q", f.Type)
	}
	return nil
}

func isValidFilterValue(v string, allowed []string) bool {
	return slices.Contains(allowed, v)
}

if err := bd("ado", "sync", filterFlags...); err != nil {
	if strings.Contains(err.Error(), "invalid pull filter") {
		log.Printf("fix filter flags or ado config: %v", err)
	}
	return err
}

When it happens

Trigger: buildADOPullFilters produces a non-nil filter set whose Validate() fails — e.g. an invalid state name, malformed area/iteration path, contradictory filter flags, or an invalid value in the ado config's pull-filter section.

Common situations: Typo in a work item type or state ('activ' vs 'active'); a filter copied from another org with different area paths; config file edited by hand with wrong casing; a flag added in a newer bd version used with an older binary (unknown/invalid combination).

Related errors

• initializing Azure DevOps tracker: %w
• Linear project milestone is missing id
• failed to get work item states: %w
• Failed to fetch ADO #%d for link sync: %v
• Link sync ADO #%d: %v

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/a00222d7027cf9c8. Report an issue: GitHub.