Jguer/yay · error

failed to retrieve aur Cache

Error message

failed to retrieve aur Cache: %w

What it means

NewRuntime wraps any failure from building the AUR metadata cache (metadata.NewCache with a cache file path, request editor and base URL) into 'failed to retrieve aur Cache: <cause>'. The library throws it because without the on-disk AUR cache (aur.json in the build dir) it cannot serve package metadata. It is a wrap of the underlying cause, so the real problem (network, bad URL, unwritable cache path) is in the %w chain.

Solutions

1. Check the wrapped cause with errors.Unwrap/ %+v to see whether it is a network error, bad URL, or file error
2. Verify cfg.AURURL is a valid AUR metadata base URL and reachable (curl it)
3. Ensure cfg.BuildDir exists and is writable so aur.json can be created
4. Delete a possibly corrupt aur.json in the build dir and retry
5. Fix network/proxy/VPN connectivity, then rerun

Example fix

// before
rt, err := runtime.NewRuntime(cfg)
if err != nil { log.Fatal(err) }
// after
rt, err := runtime.NewRuntime(cfg)
if err != nil {
	log.Fatalf("runtime init failed (check AURURL/BuildDir/network): %v", err)
}

if _, err := os.Stat(filepath.Join(cfg.BuildDir, "aur.json")); err != nil { os.MkdirAll(cfg.BuildDir, 0o755) }
if resp, err := http.Get(cfg.AURURL); err != nil || resp.StatusCode != 200 { /* fix AURURL/network before NewRuntime */ }

func aurCacheReachable(cfg *Config) bool {
	if cfg == nil || cfg.AURURL == "" { return false }
	resp, err := http.Head(cfg.AURURL)
	return err == nil && resp.StatusCode == 200
}

rt, err := runtime.NewRuntime(cfg)
var aurCacheErr *fmt.WrapError
if errors.As(err, &aurCacheErr) && strings.Contains(err.Error(), "failed to retrieve aur Cache") {
	// fall back to RPC-only or offline mode
}

When it happens

Trigger: Calling NewRuntime (directly from main/handleCmd or in tests like TestBuildRuntime) when metadata.NewCache fails: the AUR base URL is unreachable/misconfigured (cfg.AURURL), the cache file aur.json cannot be created/read under cfg.BuildDir, or the HTTP client setup fails.

Common situations: First run with no network or a proxy blocking aur.archlinux.org; a custom AURURL pointing at a mirror that is down or misspelled; a read-only or non-existent BuildDir so aur.json cannot be written; corrupted/stale aur.json causing a read error.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• failed to retrieve aur Cache
• invalid status code
• package not found in repos
• problem importing keys
• failed to parse

AI-assisted analysis of Jguer/yay@328f4b4939 (2026-09-07). Data as JSON: /api/errors/6c2b4aad0631e12e. Report an issue: GitHub.

Appendix: source

Thrown at pkg/runtime/runtime.go:97

	voteClient.SetCredentials(
		os.Getenv("AUR_USERNAME"),
		os.Getenv("AUR_PASSWORD"))

	userAgentFn := func(ctx context.Context, req *http.Request) error {
		req.Header.Set("User-Agent", userAgent)
		return nil
	}

	var aurCache aur.QueryClient
	aurCache, errAURCache := metadata.New(
		metadata.WithHTTPClient(httpClient),
		metadata.WithCacheFilePath(filepath.Join(cfg.BuildDir, "aur.json")),
		metadata.WithRequestEditorFn(userAgentFn),
		metadata.WithBaseURL(cfg.AURURL),
		metadata.WithDebugLogger(logger.Debugln),
	)
	if errAURCache != nil {
		return nil, fmt.Errorf(gotext.Get("failed to retrieve aur Cache")+": %w", errAURCache)
	}

	aurClient, errAUR := rpc.NewClient(
		rpc.WithHTTPClient(httpClient),
		rpc.WithBaseURL(cfg.AURRPCURL),
		rpc.WithRequestEditorFn(userAgentFn),
		rpc.WithLogFn(logger.Debugln))
	if errAUR != nil {
		return nil, errAUR
	}

	if cfg.UseRPC {
		aurCache = aurClient
	}

	pacmanConf, useColor, err := retrievePacmanConfig(cmdArgs, cfg.PacmanConf)
	if err != nil {
		return nil, err

View on GitHub (pinned to 328f4b4939)