What causes "stage index is unavailable" in siyuan-note/siyuan?

Treat this as a symptom of getStageIndex failing — check kernel logs for the preceding 'bazaar hash unavailable' or 'get community stage index' lines

siyuan-note/siyuan · error

stage index is unavailable

Error message

stage index is unavailable

What it means

GetExistingBazaarPackageNames filters the requested package names against the official stage index. It calls getStageIndex first; if that succeeds but returns a nil index (a defensive branch), it returns this sentinel error. It also propagates any error from getStageIndex unchanged.

Source

Thrown at kernel/bazaar/stage.go:280

		}
	})
	return stageIndex.reposByURL[url]
}

// HasBazaarPackage 判断指定名称是否存在于官方集市 Stage 索引中。
func HasBazaarPackage(ctx context.Context, pkgType, packageName string) (bool, error) {
	packageNames, err := GetExistingBazaarPackageNames(ctx, pkgType, []string{packageName})
	return 0 < len(packageNames), err
}

// GetExistingBazaarPackageNames 筛选存在于官方集市 Stage 索引中的包名。
func GetExistingBazaarPackageNames(ctx context.Context, pkgType string, packageNames []string) ([]string, error) {
	stageIndex, err := getStageIndex(ctx, pkgType)
	if nil != err {
		return nil, err
	}
	if nil == stageIndex {
		return nil, errors.New("stage index is unavailable")
	}
	official := make(map[string]bool, len(stageIndex.Repos))
	for _, repo := range stageIndex.Repos {
		if nil != repo && nil != repo.Package {
			official[repo.Package.Name] = true
		}
	}
	ret := make([]string, 0, len(packageNames))
	for _, packageName := range packageNames {
		if official[packageName] {
			ret = append(ret, packageName)
		}
	}
	return ret, nil
}

// bazaarStats 集市包统计信息
type bazaarStats struct {

View on GitHub (pinned to 8641553a1f)

Solutions

Treat this as a symptom of getStageIndex failing — check kernel logs for the preceding 'bazaar hash unavailable' or 'get community stage index' lines
Restore connectivity to rhy and BazaarOSSServer, then retry
If the nil-index branch fires repeatedly, inspect getStageIndex's SetSuccessResult handling for unmarshal issues
For install/update flows, surface 'marketplace index unavailable' and let the user retry rather than failing silently

Example fix

// before
if nil == stageIndex {
    return nil, errors.New("stage index is unavailable")
}
// after (log which pkgType failed for easier triage)
if nil == stageIndex {
    logging.LogErrorf("stage index for %s is unavailable", pkgType)
    return nil, fmt.Errorf("stage index is unavailable for %s", pkgType)
}

Defensive patterns

Strategy: fallback

Validate before calling

// pre-check marketplace metadata availability before querying packages
if util.GetRhyBazaarHash(ctx) == "" {
    return errors.New("marketplace metadata currently unavailable")
}

Try / catch

names, err := GetExistingBazaarPackageNames(ctx, "plugins", []string{"foo"})
if err != nil && strings.Contains(err.Error(), "stage index") {
    // fall back to locally installed package list
}

Prevention

Do not assume network availability when checking marketplace packages; always handle the error
Maintain a local cache of previously fetched stage indexes for fallback
Log pkgType and hash with the failure to speed up diagnosis

When it happens

Trigger: Calling GetExistingBazaarPackageNames (e.g. through HasBazaarPackage) when the stage index cannot be fetched — rhy hash unavailable, OSS non-200, or the nil-index defensive branch fires.

Common situations: Offline environment or blocked rhy/OSS endpoints; stale bazaar hash; rhy/OSS outages while checking whether a package exists before install/update.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/f236e47313f902f1. Report an issue: GitHub.