gastownhall/beads · error

initializing Notion tracker: %w

Error message

initializing Notion tracker: %w

What it means

This wraps any failure from notion.Tracker.Init during `bd notion push`. Init validates the Notion integration (token, database/page config) and prepares the tracker against the store. A failure here means the Notion tracker could not be set up and the push aborts.

Source

Thrown at cmd/bd/sync_push_pull.go:857

		CheckReadonly("notion push")
	}

	cfg := getNotionConfig()
	auth, err := resolveNotionAuth(cmd.Context())
	if err != nil {
		return err
	}
	if err := validateNotionConfig(cfg, auth); err != nil {
		return err
	}
	if err := ensureStoreActive(); err != nil {
		return fmt.Errorf("database not available: %w", err)
	}

	ctx := cmd.Context()
	nt := &notion.Tracker{}
	if err := nt.Init(ctx, store); err != nil {
		return fmt.Errorf("initializing Notion tracker: %w", err)
	}

	engine := tracker.NewEngine(nt, store, actor)
	unsupportedStats := newNotionUnsupportedPushStats()
	engine.PushHooks = buildNotionPushHooks(ctx, nt, unsupportedStats)
	engine.OnMessage = func(msg string) { fmt.Println("  " + msg) }
	engine.OnWarning = func(msg string) { fmt.Fprintf(os.Stderr, "Warning: %s\n", msg) }

	result, syncErr := engine.Sync(ctx, tracker.SyncOptions{
		Push:             true,
		Pull:             false,
		DryRun:           dryRun,
		ExcludeEphemeral: true,
		IssueIDs:         args,
	})
	if syncErr != nil {
		return syncErr
	}

View on GitHub (pinned to 71377f2769)

Solutions

  1. Verify NOTION_TOKEN (or configured secret) is set and belongs to a valid internal integration
  2. In Notion, open the target database → Connections → add your integration
  3. Check the configured Notion database ID and workspace mapping in the beads Notion config
  4. Test connectivity: curl -H "Authorization: Bearer $NOTION_TOKEN" https://api.notion.com/v1/users/me
  5. Read the wrapped cause after this message for the specific Notion API failure

Example fix

// before
bd notion push bd-42
// Error: initializing Notion tracker: ... code: unauthorized
// after
export NOTION_TOKEN="secret_..."  # valid integration secret, shared with the DB
bd notion push bd-42
Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$NOTION_TOKEN" ]; then echo "NOTION_TOKEN not set" >&2; exit 1; fi
curl -fsS -H "Authorization: Bearer $NOTION_TOKEN" -H "Notion-Version: 2022-06-28" https://api.notion.com/v1/users/me > /dev/null || { echo "Notion token invalid" >&2; exit 1; }
bd notion push bd-42

Try / catch

if err := nt.Init(ctx, store); err != nil {
    var apiErr *notion.APIError
    if errors.As(err, &apiErr) && apiErr.Code == "unauthorized" {
        return fmt.Errorf("Notion token rejected; re-share database with integration and refresh token")
    }
    return fmt.Errorf("initializing Notion tracker: %w", err)
}

Prevention

When it happens

Trigger: Running `bd notion push <id>` when notion.Tracker.Init(ctx, store) fails — missing/invalid NOTION_TOKEN, no Notion database configured, integration not shared with the target database, or API connectivity failure.

Common situations: Notion integration secret expired or revoked; the internal integration was never granted access to the target Notion database in Notion's UI; wrong database ID in config; network/proxy blocking api.notion.com.

Related errors

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