plandex-ai/plandex · error

failed to check outdated context: %s

Error message

failed to check outdated context: %s

What it means

CheckOutdatedContextWithOutput wraps any failure from CheckOutdatedContext (which hashes local files/urls/trees/maps against stored context state) with this generic prefix. It means the staleness check itself could not complete, so the CLI cannot tell whether plan context is current. The inner error (%s) names the actual cause, e.g. unreadable file or stat failure.

Source

Thrown at app/cli/lib/context_update.go:45

	}

	var contexts []*shared.Context

	if maybeContexts != nil {
		contexts = maybeContexts
	} else {
		res, err := api.Client.ListContext(CurrentPlanId, CurrentBranch)
		if err != nil {
			term.StopSpinner()
			return false, false, fmt.Errorf("failed to list context: %s", err)
		}
		contexts = res
	}

	outdatedRes, err := CheckOutdatedContext(contexts, projectPaths)
	if err != nil {
		term.StopSpinner()
		return false, false, fmt.Errorf("failed to check outdated context: %s", err)
	}

	if !quiet {
		term.StopSpinner()
	}

	if len(outdatedRes.UpdatedContexts) == 0 && len(outdatedRes.RemovedContexts) == 0 {
		if !quiet {
			fmt.Println("✅ Context is up to date")
		}
		return false, false, nil
	}
	if len(outdatedRes.UpdatedContexts) > 0 {
		types := []string{}
		if outdatedRes.NumFiles > 0 {
			lbl := "file"
			if outdatedRes.NumFiles > 1 {
				lbl = "files"

View on GitHub (pinned to e2d772072e)

Solutions

1. Read the wrapped inner error to find the specific file or operation that failed
2. Verify the file exists and is readable by the current user (ls -l, cat the file)
3. Remove stale context entries for files that no longer exist (plandex context rm) and re-add them
4. Re-run from the project root so relative context file paths resolve correctly

Example fix

// before: blindly calling and failing on unreadable file
_, _, err := lib.CheckOutdatedContextWithOutput(false, false, nil, projectPaths)
// after: filter unreadable files out first
for _, c := range contexts {
    if c.ContextType == shared.ContextFileType {
        if _, err := os.ReadFile(c.FilePath); err != nil {
            fmt.Printf("skipping unreadable %s: %v\n", c.FilePath, err)
        }
    }
}
outdated, updated, err := lib.CheckOutdatedContextWithOutput(false, false, contexts, projectPaths)

func allContextFilesReadable(contexts []*shared.Context) error {
    for _, c := range contexts {
        if c.ContextType == shared.ContextFileType {
            if _, err := os.ReadFile(c.FilePath); err != nil {
                return fmt.Errorf("context file %s unreadable: %w", c.FilePath, err)
            }
        }
    }
    return nil
}

outdated, updated, err := lib.CheckOutdatedContextWithOutput(false, false, nil, paths)
if err != nil {
    if strings.Contains(err.Error(), "failed to check outdated context") {
        // inspect inner cause; refresh context list or fix file access
        return fmt.Errorf("stale-context check failed: %w", err)
    }
    return err
}

When it happens

Trigger: Calling CheckOutdatedContextWithOutput when a context file exists but cannot be read (permission denied, deleted between stat and read, is a directory), or any lower-level failure inside CheckOutdatedContext such as file-info retrieval or map-tree computation errors.

Common situations: Files were moved/renamed after being added to context; read permissions changed (chmod, different user/CI environment); symlinks pointing to missing targets; running in a container where the mounted project path differs.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• no project root found
• failed to check context conflicts: %v
• failed to check context conflicts: %v
• error creating plan dir: %v
• error checking if settings-v2.json exists: %v

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