Tencent/WeKnora · error

invalid fileName: contains path traversal

Error message

invalid fileName: contains path traversal

What it means

Traversal validation in SafeFileName: after reducing the input with Base/Clean, the result still contains '..' anywhere, meaning the value embeds a traversal sequence that survived the first checks. The function rejects it outright so only a plain final path component can ever be used for file writes.

Source

Thrown at internal/utils/security.go:139

	sep := string(filepath.Separator)
	if absPath != absBase && !strings.HasPrefix(absPath, absBase+sep) {
		return "", fmt.Errorf("path traversal denied: path is outside base directory")
	}
	return absPath, nil
}

// SafeFileName 校验并返回安全的“仅文件名”部分，防止路径遍历。
// 仅保留最后一个路径成分，禁止 ".."、空名或仅含点，用于 SaveBytes 等场景。
func SafeFileName(fileName string) (string, error) {
	if fileName == "" {
		return "", fmt.Errorf("fileName cannot be empty")
	}
	base := filepath.Base(filepath.Clean(fileName))
	if base == "" || base == "." || base == ".." {
		return "", fmt.Errorf("invalid fileName: path traversal or empty name")
	}
	if strings.Contains(base, "..") {
		return "", fmt.Errorf("invalid fileName: contains path traversal")
	}
	if len(base) > 255 {
		return "", fmt.Errorf("fileName too long")
	}
	return base, nil
}

// SafeObjectKey 校验对象存储的 key（如 COS/MinIO objectName），禁止包含 ".." 等路径遍历
func SafeObjectKey(objectKey string) error {
	if objectKey == "" {
		return fmt.Errorf("object key cannot be empty")
	}
	if strings.Contains(objectKey, "..") {
		return fmt.Errorf("object key contains path traversal")
	}
	return nil
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Sanitize or replace '..' sequences in user-supplied names
2. Reject the upload and log the traversal attempt
3. Generate a server-side safe name instead of trusting the client name

When it happens

Trigger: Thrown at internal/utils/security.go:139 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/826e16bf44c204db. Report an issue: GitHub.