What causes "failed to build inventory for tool scope map: %w" in github/github-mcp-server?

Read the wrapped error after the colon - it names the actual builder failure that must be fixed

failed to build inventory for tool scope map: %w

Error message

failed to build inventory for tool scope map: %w

What it means

Thrown during HTTP server startup when initGlobalToolScopeMap cannot build the tool inventory that feeds the global tool-to-OAuth-scope map. It runs inventory.NewBuilder().SetTools(github.AllTools(t, github.WithHost(hostType))).Build() over the full tool catalog for the configured host type, so a failure means the static catalog itself is inconsistent for this build/host combination, not bad request input. The wrapped error (%w) names the underlying builder failure.

Source

Thrown at pkg/http/server.go:253

// resolveListenAddress returns the address string passed to http.Server.
// When host is empty the server binds to all interfaces on the given port;
// otherwise host and port are joined into a single address.
func resolveListenAddress(host string, port int) string {
	if host == "" {
		return fmt.Sprintf(":%d", port)
	}
	return net.JoinHostPort(host, strconv.Itoa(port))
}

func initGlobalToolScopeMap(t translations.TranslationHelperFunc, hostType utils.HostType) error {
	// Build inventory with all tools to extract scope information
	inv, err := inventory.NewBuilder().
		SetTools(github.AllTools(t, github.WithHost(hostType))).
		Build()

	if err != nil {
		return fmt.Errorf("failed to build inventory for tool scope map: %w", err)
	}

	// Initialize the global scope map
	scopes.SetToolScopeMapFromInventory(inv)

	return nil
}

// createHTTPFeatureChecker creates a feature checker that resolves static CLI
// features plus per-request header features and insiders mode.
func createHTTPFeatureChecker(enabledFeatures []string, insidersMode bool) inventory.FeatureFlagChecker {
	return func(ctx context.Context, flag string) (bool, error) {
		headerFeatures := ghcontext.GetHeaderFeatures(ctx)
		features := make([]string, 0, len(enabledFeatures)+len(headerFeatures))
		features = append(features, enabledFeatures...)
		features = append(features, headerFeatures...)

		effective := github.ResolveFeatureFlags(features, insidersMode || ghcontext.IsInsidersMode(ctx))

View on GitHub (pinned to 0ea1f775a7)

Solutions

Read the wrapped error after the colon - it names the actual builder failure that must be fixed
Boot the same config in stdio mode to check whether the tool catalog builds at all
Verify --github-host/host-type matches the toolsets enabled: GHES hosts expose fewer tools than dotcom
If the binary is unmodified, file an issue including the version and the full wrapped error chain

Defensive patterns

Strategy: try-catch

Validate before calling

// CI smoke test: prove the catalog builds for every host type you deploy
for _, ht := range []utils.HostType{utils.HostTypeDotcom, utils.HostTypeGHES} {
	if _, err := inventory.NewBuilder().
		SetTools(github.AllTools(translations.NullTranslationHelper, github.WithHost(ht))).Build(); err != nil {
		t.Fatalf("tool catalog broken for host %v: %v", ht, err)
	}
}

Try / catch

if err := initGlobalToolScopeMap(t, hostType); err != nil {
	// not transient: surface the wrapped %w chain and stop - never retry with the same config
	log.Error("startup failed: tool scope map", "err", err)
	os.Exit(1)
}

Prevention

Smoke-test server startup for each host type in CI so catalog regressions are caught pre-deploy
Pin the server version and re-validate custom tool registrations on every upgrade
Treat this error as a build/config defect, not a runtime condition

When it happens

Trigger: Starting the server in HTTP/streaming mode when Build() fails while resolving the complete tool set: a toolset definition referencing a tool not registered for the selected host type, or conflicting builder options applied over AllTools. The wrapped error is frequently itself 'unknown tools specified in WithTools' from the same package.

Common situations: Upgrading to a release whose tool catalog changed; custom forks adding tools with incomplete registrations; running with a GHES host type where dotcom-only tools are referenced in config.

Related errors

AI-assisted analysis of github/github-mcp-server@0ea1f775a7 (2026-08-15). Data as JSON: /api/errors/2120cff16f00e4ad. Report an issue: GitHub.