vxcontrol/pentagi · error

path query parameter is required

Error message

path query parameter is required

What it means

ResolveCachedPath validates a user-supplied path for accessing flow files before any filesystem access. It rejects an empty or whitespace-only reqPath because a blank path cannot be resolved to any file inside the flow's data directory. The check is the first guard in a chain that also enforces relative paths and an allow-listed directory prefix.

Source

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

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)
}

func FlowContainerDir(dataDir string, flowID uint64) string {
	return filepath.Join(FlowDataDir(dataDir, flowID), ContainerDirName)
}

func FlowResourcesDir(dataDir string, flowID uint64) string {
	return filepath.Join(FlowDataDir(dataDir, flowID), ResourcesDirName)
}

func ResolveCachedPath(dataDir string, flowID uint64, reqPath string) (string, error) {
	if strings.TrimSpace(reqPath) == "" {
		return "", errors.New("path query parameter is required")
	}

	cleaned := filepath.Clean(filepath.FromSlash(strings.ReplaceAll(reqPath, "\\", "/")))
	if filepath.IsAbs(cleaned) {
		return "", fmt.Errorf("path must be relative (no leading /)")
	}

	parts := strings.SplitN(cleaned, string(filepath.Separator), 2)
	if parts[0] != UploadsDirName && parts[0] != ContainerDirName && parts[0] != ResourcesDirName {
		return "", fmt.Errorf("path must start with '%s', '%s', or '%s'", UploadsDirName, ContainerDirName, ResourcesDirName)
	}

	flowDataDir := FlowDataDir(dataDir, flowID)
	absPath := filepath.Join(flowDataDir, cleaned)
	if !IsWithinDir(absPath, flowDataDir) {
		return "", fmt.Errorf("path escapes the flow data directory")
	}

View on GitHub (pinned to ea665308ba)

Solutions

1. Pass a non-empty path, e.g. 'uploads/report.pdf', 'containers/...', or 'resources/...' as the path query parameter
2. Check the caller: if the path comes from user input, validate non-empty before invoking the API
3. If building URLs programmatically, ensure the query parameter is actually included and not stripped by a template or client

Example fix

// before
client.get(`/flows/${flowID}/files?path=`)
// after
client.get(`/flows/${flowID}/files?path=${encodeURIComponent('uploads/report.pdf')}`)

if (!reqPath || !reqPath.trim()) throw new Error('path query parameter is required before calling the API');

const hasPath = (p: unknown): p is string => typeof p === 'string' && p.trim().length > 0;

try {
  const resolved = await api.resolveCachedPath(flowID, reqPath);
} catch (e) {
  if (e.message.includes('path query parameter is required')) {
    // prompt user / fix caller to supply a path
  }
}

When it happens

Trigger: Calling ResolveCachedPath (directly or via AddResourceFromFlow / the HTTP handler calling it) with an empty string, a string of spaces/tabs, or omitting the required path query parameter on the request that triggers this resolver.

Common situations: A frontend or script hits the flow-files endpoint without appending ?path=...; a tool integration builds the URL with an empty variable because the file path was never populated; URL encoding drops the parameter entirely.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• path must be relative (no leading /)
• FlowFiles.NotFound
• path is required
• invalid path component '%s': %w
• invalid file name

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