invalid hub index: %w. Run 'sudo cscli hub update' to downlo

Error message

invalid hub index: %w. Run 'sudo cscli hub update' to download the index again

What it means

Hub.Load wraps any error from parseIndex (unreadable, unparseable, or structurally invalid index) with remediation text telling the user to re-run `cscli hub update`. Load cannot proceed to localSync without a valid in-memory item map.

Source

Thrown at pkg/cwhub/hub.go:64

	if logger == nil {
		logger = logrus.New()
		logger.SetOutput(io.Discard)
	}

	hub := &Hub{
		local:  local,
		logger: logger,
	}

	return hub, nil
}

// Load reads the state of the items on disk.
func (h *Hub) Load() error {
	h.logger.Debugf("loading hub idx %s", h.local.HubIndexFile)

	if err := h.parseIndex(); err != nil {
		return fmt.Errorf("invalid hub index: %w. Run 'sudo cscli hub update' to download the index again", err)
	}

	return h.localSync()
}

// parseIndex takes the content of an index file and fills the map of associated parsers/scenarios/collections.
func (h *Hub) parseIndex() error {
	bidx, err := os.ReadFile(h.local.HubIndexFile)
	if err != nil {
		return fmt.Errorf("unable to read index file: %w", err)
	}

	if err := json.Unmarshal(bidx, &h.items); err != nil {
		return fmt.Errorf("failed to parse index: %w", err)
	}

	// Iterate over the different types to complete the struct
	for _, itemType := range ItemTypes {

View on GitHub (pinned to 909b515798)

Solutions

Run `sudo cscli hub update` to regenerate the index file
Inspect /var/lib/crowdsec/data/hub/.index.json validity (e.g. `jq . <file>`)
If unreadable/missing, check permissions and re-download via `cscli hub update`
Restore default hub data or reinstall if corruption persists

Defensive patterns

Strategy: try-catch

Validate before calling

if _, err := os.Stat(hubIndexFile); err != nil {
    return fmt.Errorf("hub index missing (%v); run 'cscli hub update' first", err)
}

Try / catch

if err := hub.Load(); err != nil {
    if strings.Contains(err.Error(), "invalid hub index") {
        logger.Error("hub index invalid — running 'cscli hub update' then retrying")
        if rerr := runHubUpdate(ctx); rerr != nil { return rerr }
        return hub.Load()
    }
    return err
}

Prevention

Always run `cscli hub update` after install and before hub list/upgrade operations
Treat the index file as machine-managed; never edit it by hand
Re-download the index after any crowdsec version upgrade

When it happens

Trigger: Calling Hub.Load when the on-disk hub index file is missing, unreadable, invalid JSON, or contains entries with missing metadata (all parseIndex failure modes).

Common situations: First run before any `cscli hub update`, disk corruption, manual edits to .index.json, or upgrading crowdsec against an index written by an incompatible version.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of crowdsecurity/crowdsec@909b515798 (2026-09-06). Data as JSON: /api/errors/b76a134af62b6e9c. Report an issue: GitHub.