What causes "reading resources cache: %w" in vxcontrol/pentagi?

Create the resources directory when the flow is initialized or on first resource add

reading resources cache: %w

Error message

reading resources cache: %w

What it means

List() fails while recursively listing the per-flow resources directory (FlowResourcesDir). Third of the three cache-read steps; if it fails the whole file listing is aborted and the wrapped error returned.

Source

Thrown at backend/pkg/flowfiles/files.go:69

type TarEntry struct {
	LocalPath string
	TarPath   string
}

func List(dataDir string, flowID uint64) (Files, error) {
	uploadsEntries, err := ListDirEntries(FlowUploadsDir(dataDir, flowID), UploadsDirName)
	if err != nil {
		return Files{}, fmt.Errorf("reading uploads cache: %w", err)
	}

	containerEntries, err := ListDirEntriesRecursive(FlowContainerDir(dataDir, flowID), ContainerDirName)
	if err != nil {
		return Files{}, fmt.Errorf("reading container cache: %w", err)
	}

	resourcesEntries, err := ListDirEntriesRecursive(FlowResourcesDir(dataDir, flowID), ResourcesDirName)
	if err != nil {
		return Files{}, fmt.Errorf("reading resources cache: %w", err)
	}

	files := append(uploadsEntries, containerEntries...)
	files = append(files, resourcesEntries...)
	Sort(files)
	return Files{
		Files: files,
		Total: uint64(len(files)),
	}, nil
}

func FlowDataDir(dataDir string, flowID uint64) string {
	return filepath.Join(dataDir, fmt.Sprintf("flow-%d-data", flowID))
}

func FlowUploadsDir(dataDir string, flowID uint64) string {
	return filepath.Join(FlowDataDir(dataDir, flowID), UploadsDirName)
}

View on GitHub (pinned to ea665308ba)

Solutions

Create the resources directory when the flow is initialized or on first resource add
Treat a missing directory as an empty resources list
Check ownership/permissions of FlowResourcesDir(dataDir, flowID)
Verify the underlying volume health and free space

Example fix

// before
return Files{}, fmt.Errorf("reading resources cache: %w", err)
// after
if os.IsNotExist(err) {
    resourcesEntries = nil
} else {
    return Files{}, fmt.Errorf("reading resources cache: %w", err)
}

Defensive patterns

Strategy: validation

Validate before calling

if _, err := os.Stat(files.FlowResourcesDir(dataDir, flowID)); os.IsNotExist(err) {
    os.MkdirAll(files.FlowResourcesDir(dataDir, flowID), 0o755)
}

Type guard

func isMissingResourcesCache(err error) bool {
    return strings.Contains(err.Error(), "reading resources cache") && errors.Is(err, os.ErrNotExist)
}

Try / catch

files, err := flowfiles.List(dataDir, flowID)
if err != nil && strings.Contains(err.Error(), "reading resources cache") {
    if os.IsNotExist(err) { files = flowfiles.Files{} } else { return err }
}

Prevention

Create the resources dir on flow init or first resource add
Keep resource-writer and flow-reader user identities aligned
Alert on filesystem errors from the data volume
Use the same permission model across all three cache roots

When it happens

Trigger: List(dataDir, flowID) with a missing/unreadable resources directory or an OS readdir error during recursion.

Common situations: Resources never added to the flow so the dir was never created; resources uploaded by another process with different ownership; disk/volume issues on the data mount.

Related errors

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/c3695a691ec09846. Report an issue: GitHub.