plandex-ai/plandex · error

error checking cached file map: %v

Error message

error checking cached file map: %v

What it means

When loading a project map (DefsOnly), MustLoadContext calls api.Client.LoadCachedFileMap to check which file-map paths are already cached server-side; this error means that call failed. It aborts via onErr since the cached-map optimization can't be validated.

Source

Thrown at app/cli/lib/context_load.go:179

		if params.DefsOnly {
			for _, inputFilePath := range inputFilePaths {
				composite := strings.Join([]string{string(shared.ContextMapType), inputFilePath}, "|")
				if existsByComposite[composite] != nil {
					alreadyLoadedByComposite[composite] = existsByComposite[composite]
					continue
				}

				toLoadMapPaths = append(toLoadMapPaths, inputFilePath)
			}

			var uncachedMapPaths []string

			res, err := api.Client.LoadCachedFileMap(CurrentPlanId, CurrentBranch, shared.LoadCachedFileMapRequest{
				FilePaths: toLoadMapPaths,
			})

			if err != nil {
				onErr(fmt.Errorf("error checking cached file map: %v", err))
			}

			if res.LoadRes != nil {
				if res.LoadRes.MaxTokensExceeded {
					term.StopSpinner()
					overage := res.LoadRes.TotalTokens - res.LoadRes.MaxTokens

					term.OutputErrorAndExit("Update would add %d 🪙 and exceed token limit (%d) by %d 🪙\n", res.LoadRes.TokensAdded, res.LoadRes.MaxTokens, overage)
				}

				cachedMapLoadRes = res.LoadRes
				cachedMapPaths = res.CachedByPath

				for _, path := range toLoadMapPaths {
					if !cachedMapPaths[path] {
						uncachedMapPaths = append(uncachedMapPaths, path)
					}
				}

View on GitHub (pinned to e2d772072e)

Solutions

1. Check connectivity and retry the load command
2. Re-authenticate if auth-related
3. Ensure client and server versions match (update CLI/server)
4. Reduce the number of map paths loaded at once if the request is timing out

Example fix

// before
res, err := api.Client.LoadCachedFileMap(CurrentPlanId, CurrentBranch, shared.LoadCachedFileMapRequest{
	FilePaths: toLoadMapPaths,
})
if err != nil {
	onErr(fmt.Errorf("error checking cached file map: %v", err))
}
// after
res, err := api.Client.LoadCachedFileMap(CurrentPlanId, CurrentBranch, shared.LoadCachedFileMapRequest{
	FilePaths: toLoadMapPaths,
})
if err != nil {
	// fall back to uncached map build instead of exiting
	term.StopSpinner()
	term.OutputErrorAndExit("error checking cached file map: %v (will rebuild maps from scratch)", err)
}

// only query the cache for a bounded path list
if len(toLoadMapPaths) > 500 {
	log.Printf("%d map paths — consider batching the cached-map lookup", len(toLoadMapPaths))
}

// Go: nil-guard the nested LoadRes before use
func loadResSafe(res *shared.LoadCachedFileMapResponse) (*shared.LoadContextResponse, bool) {
	if res == nil || res.LoadRes == nil { return nil, false }
	return res.LoadRes, true
}

// Go: degrade gracefully to uncached map build
res, err := api.Client.LoadCachedFileMap(planId, branch, req)
if err != nil {
	log.Printf("cached map check failed (%v); rebuilding maps from scratch", err)
	uncachedMapPaths = toLoadMapPaths
} else { /* normal path */ }

When it happens

Trigger: api.Client.LoadCachedFileMap(CurrentPlanId, CurrentBranch, req) returns an error — network failure, auth expiry, invalid plan/branch, or server error while looking up cached maps for FilePaths.

Common situations: Offline/proxy issue while running `plandex load --map`; stale session token; server version mismatch where the cached-file-map endpoint is unavailable; very large path list timing out.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• error signing in: %v
• error listing contexts: %v
• error getting context body: %v
• error getting default config: %v
• error creating plan: %v

AI-assisted analysis of plandex-ai/plandex@e2d772072e (2026-09-05). Data as JSON: /api/errors/bc81749f88f3cc68. Report an issue: GitHub.