vxcontrol/pentagi · error

file name contains unsupported characters

Error message

file name contains unsupported characters

What it means

validatePathComponent rejects components containing characters that are illegal or dangerous across major filesystems — '/', '\\', ':', '*', '?', '"', '<', '>', '|' — returning 'file name contains unsupported characters'. Since '/' and '\\' are path separators (already split upstream), this mostly catches Windows-reserved and glob characters inside a single segment.

Source

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

	return path.Join(parts...), nil
}

func validatePathComponent(component string) (string, error) {
	cleanName := strings.TrimSpace(component)
	if cleanName == "." || cleanName == ".." || cleanName == "/" || cleanName == "" {
		return "", fmt.Errorf("invalid file name")
	}
	if len(cleanName) > MaxFileNameLength {
		return "", fmt.Errorf("file name is too long")
	}
	for _, r := range cleanName {
		if r < 0x20 || r == 0x7f {
			return "", fmt.Errorf("file name contains control characters")
		}
		switch r {
		case '/', '\\', ':', '*', '?', '"', '<', '>', '|':
			return "", fmt.Errorf("file name contains unsupported characters")
		}
	}

	return cleanName, nil
}

func NewFile(info os.FileInfo, sourceDir string) File {
	return NewFileWithPath(info, path.Join(sourceDir, info.Name()))
}

func NewFileWithPath(info os.FileInfo, filePath string) File {
	return File{
		ID:         ID(filePath),
		Name:       info.Name(),
		Path:       filePath,
		Size:       info.Size(),
		IsDir:      info.IsDir(),
		ModifiedAt: info.ModTime(),

View on GitHub (pinned to ea665308ba)

Solutions

1. Replace the unsupported characters (e.g. ':' → '-', '*' → '_') before calling.
2. Pass glob patterns through the appropriate listing/search API instead of as literal file names.
3. Sanitize timestamps by formatting without colons (e.g. 12-30-00 instead of 12:30:00).

Example fix

// before
name, err := flowfiles.SanitizeFileName("backup_12:30:00.tar")
// after
name, err := flowfiles.SanitizeFileName(strings.ReplaceAll("backup_12:30:00.tar", ":", "-"))

var unsupported = "/:*?\"<>|\\"
func hasUnsupportedChars(s string) bool {
    return strings.ContainsAny(s, unsupported)
}

func isPortableName(s string) bool {
    return !strings.ContainsAny(s, "/:*?\"<>|\\")
}

if err != nil {
    if err.Error() == "file name contains unsupported characters" {
        return fmt.Errorf("replace : * ? \" < > | in the file name before upload")
    }
    return err
}

When it happens

Trigger: SanitizeFileName or SanitizeContainerCachePath with a component containing ':' (e.g. "C:file", time stamps like "12:30.log"), '*', '?', '"', '<', '>', or '|' (e.g. glob patterns "*.log", pipes "a|b").

Common situations: Windows-derived names with drive letters or Alternate Data Streams; agent-generated glob patterns like 'reports/*.pdf' passed as a literal file name; timestamps with colons in file names; shell redirection characters copied into names.

Related errors

• invalid file name
• file name contains control characters
• path is required
• invalid path component '%s': %w
• file name is too long

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