Skip to content

Troubleshooting and FAQ

Jump to bottom Edit New page
fasiondog edited this page Nov 22, 2025 · 1 revision

Troubleshooting and FAQ

**Referenced Files in This Document** - [readme.md](file://readme.md) - [__init__.py](file://hikyuu/__init__.py) - [hku_config_template.py](file://hikyuu/data/hku_config_template.py) - [common.py](file://hikyuu/data/common.py) - [common_sqlite3.py](file://hikyuu/data/common_sqlite3.py) - [common_mysql.py](file://hikyuu/data/common_mysql.py) - [pytdx_to_h5.py](file://hikyuu/data/pytdx_to_h5.py) - [tdx_to_h5.py](file://hikyuu/data/tdx_to_h5.py) - [mylog.py](file://hikyuu/util/mylog.py) - [check.py](file://hikyuu/util/check.py)

Table of Contents

  1. Introduction
  2. Common Installation Issues
  3. Configuration Problems
  4. Data-Related Issues
  5. Performance Optimization
  6. FAQ
  7. Getting Additional Help

Introduction

This troubleshooting and FAQ guide provides comprehensive solutions for common issues encountered when using the Hikyuu quantitative trading framework. The document covers installation problems, configuration errors, data-related issues, performance optimization tips, and frequently asked questions. All solutions are based on the actual codebase and error handling mechanisms implemented in Hikyuu.

The framework is designed for quantitative trading research, particularly focused on the Chinese A-share market. It provides a systematic approach to strategy development, backtesting, and real-time trading with high performance capabilities.

Section sources

  • readme.md

Common Installation Issues

Missing Dependencies Error

Issue: When importing Hikyuu, you encounter an error message like "Please use pipdeptree -p hikyuu to check if there are missing dependency packages."

Cause: This occurs when required Python packages are not installed or when there are version conflicts between hikyuu and its dependencies.

Solution:

  1. Check for missing dependencies using: pipdeptree -p hikyuu
  2. Install missing packages using pip: pip install package_name
  3. Ensure compatibility between hikyuu and hikyuu_plugin versions. The major version numbers should match.
  4. If using conda, create a dedicated environment: conda create -n hikyuu python=3.x

Section sources

  • init.py

Dynamic Library Loading Problems

Issue: On Windows systems, you may encounter errors related to loading dynamic libraries (DLLs).

Cause: The system cannot locate the required C++ libraries that Hikyuu depends on.

Solution:

  1. Ensure the C++ library directory is added to the system PATH environment variable.
  2. The library path is automatically added in __init__.py using os.add_dll_directory() and by modifying the PATH variable.
  3. If issues persist, manually add the hikyuu/cpp directory to your system PATH.

Section sources

  • init.py

Plugin Version Mismatch Warning

Issue: You see a warning message: "hikyuu version (x.x.x) does not match hikyuu_plugin version (y.y.y), please ensure compatible versions!"

Cause: The hikyuu and hikyuu_plugin packages have different major version numbers, which can lead to compatibility issues.

Solution:

  1. Check the installed versions: pip show hikyuu and pip show hikyuu_plugin
  2. Update both packages to ensure version compatibility: 
    pip install --upgrade hikyuu hikyuu_plugin
  3. If using specific versions, ensure the major and minor version numbers match.

Section sources

  • init.py

Configuration Problems

Missing Configuration File

Issue: When calling load_hikyuu(), you receive the error: "Configuration file does not exist: ~/.hikyuu/hikyuu.ini"

Cause: The required configuration file has not been created in the user's home directory.

Solution:

  1. The system will automatically create a default configuration file when load_hikyuu() is called without a specified config file.
  2. The default configuration is generated by generate_default_config() in hku_config_template.py.
  3. On Windows, the default data directory is set to "c:\stock", while on Linux/macOS, it's "~/stock".
  4. You can also manually create the configuration file using the templates provided in the codebase.

Section sources

  • init.py
  • hku_config_template.py

Incorrect Data Directory Configuration

Issue: Data cannot be loaded or saved, with errors indicating file or directory not found.

Cause: The data directory specified in the configuration file does not exist or has incorrect permissions.

Solution:

  1. Verify the datadir setting in your hikyuu.ini configuration file.
  2. Ensure the directory exists and is writable.
  3. The default configuration automatically creates the data directory if it doesn't exist.
  4. Check that the path uses the correct format for your operating system (forward slashes for Linux/macOS, backslashes for Windows).

Section sources

  • hku_config_template.py

Database Configuration Issues

Issue: Database connection errors when using MySQL or SQLite storage.

Cause: Incorrect database connection parameters or missing database files.

Solution:

  1. For SQLite: Ensure the database file path is correct and the directory exists.
  2. For MySQL: Verify the host, port, username, and password in the configuration.
  3. The framework automatically creates the database structure if it doesn't exist.
  4. Use the appropriate template (hdf5_template, mysql_template, or clickhouse_template) based on your storage preference.

Section sources

  • hku_config_template.py
  • common_sqlite3.py
  • common_mysql.py

Data-Related Issues

Missing Stock Data

Issue: When attempting to retrieve stock data, you receive empty results or errors indicating no data available.

Cause: The required data has not been imported into the system.

Solution:

  1. Ensure you have imported stock data using one of the data import methods:
    • pytdx_to_h5.py for importing from TDX using pytdx
    • tdx_to_h5.py for importing from local TDX files
    • pytdx_to_mysql.py for importing to MySQL
  2. Verify that the data import process completed successfully by checking the log files.
  3. Confirm that the stock code and market are correct (e.g., 'SH600000' for Shanghai market).

Section sources

  • pytdx_to_h5.py
  • tdx_to_h5.py

Data Synchronization Problems

Issue: Stock data appears to be outdated or missing recent trading days.

Cause: The data import process did not complete successfully or was interrupted.

Solution:

  1. Check the last update date in the database using get_last_date() function.
  2. Re-run the data import process, ensuring a stable internet connection.
  3. For real-time updates, use the realtime_update() function: 
    realtime_update(source='qq', delta=60)
  4. Verify that the data source (e.g., QQ, QMT) is accessible and not blocked.

Section sources

  • pytdx_to_h5.py
  • init.py

Data Format Errors

Issue: Data validation errors when importing or processing stock data.

Cause: Inconsistent data formats between the source and the expected format in Hikyuu.

Solution:

  1. The framework includes data validation in import_one_stock_data() that checks for reasonable price movements (less than 2% difference from previous close).
  2. If data validation fails, the import process will return 0 records.
  3. Ensure the data source provides data in the expected format (prices in yuan, volumes in shares).
  4. For custom data sources, implement proper data transformation before import.

Section sources

  • pytdx_to_h5.py

Performance Optimization

Slow Data Loading

Issue: Loading large amounts of data takes longer than expected.

Cause: Inefficient data access patterns or suboptimal configuration.

Solution:

  1. Use HDF5 format for data storage, which is optimized for fast access.
  2. Preload only the necessary data types and time ranges: 
    load_hikyuu(ktype_list=['day'], preload_num={'day_max': 1000})
  3. Increase the maximum number of preloaded records in the configuration file.
  4. Ensure you have sufficient RAM for caching data.

Section sources

  • init.py
  • hku_config_template.py

Memory Usage Optimization

Issue: High memory consumption when working with large datasets.

Solution:

  1. Configure selective data loading in hikyuu.ini: 
    [preload]
day = True
week = False
month = False
  2. Load only specific stocks rather than all A-shares: 
    load_hikyuu(stock_list=['SH600000', 'SZ000001'])
  3. Disable loading of unnecessary data: 
    load_hikyuu(load_history_finance=False, load_weight=False)
  4. Use Query objects to limit the time range of data retrieved.

Section sources

  • init.py

Data Import Performance

Issue: Data import process is slow or times out.

Solution:

  1. Use batch processing with appropriate step sizes:
    • Daily data: 800 records per batch
    • 5-minute data: 800 records per batch
  2. Increase the timeout settings if network latency is high.
  3. Use multiple threads for data import when supported.
  4. Consider using local TDX files instead of network APIs for faster import.

Section sources

  • pytdx_to_h5.py

FAQ

Data Management

Q: How do I change the default data storage location? A: Modify the datadir parameter in your hikyuu.ini configuration file. The default location is "c:\stock" on Windows and "~/stock" on Linux/macOS.

Q: What data formats are supported? A: Hikyuu supports HDF5, MySQL, ClickHouse, and SQLite for data storage. HDF5 is the default and recommended format due to its speed and efficiency.

Q: How do I update my data to the latest trading day? A: Use the realtime_update() function or re-run the data import process. The system will automatically detect and import only new data.

Strategy Development

Q: How do I create a simple trading strategy? A: Use the provided components to build your strategy:

my_tm = crtTM(init_cash=300000)
my_sg = SG_Flex(EMA(CLOSE(), n=5), slow_n=10)
my_mm = MM_FixedCount(1000)
sys = SYS_Simple(tm=my_tm, sg=my_sg, mm=my_mm)
sys.run(sm['sz000001'], Query(-150))

Q: Can I use custom indicators in my strategies? A: Yes, you can create custom indicators by extending the Indicator class or by combining existing indicators using mathematical operations.

Backtesting

Q: How do I perform a backtest on multiple stocks? A: Use the block system to define a group of stocks and iterate through them:

for stock in blocka:
    sys.run(stock, query)

Q: How accurate are the backtesting results? A: The framework accounts for transaction costs, slippage, and other real-world factors. However, results may differ from actual trading due to market impact and other unpredictable factors.

Q: Can I backtest intraday strategies? A: Yes, the framework supports multiple time frames including minute data (1min, 5min, etc.) for intraday strategy testing.

Configuration

Q: How do I configure the system to use MySQL instead of HDF5? A: Change the type parameter in the [kdata] section of hikyuu.ini from 'hdf5' to 'mysql' and provide the appropriate connection details.

Q: What is the purpose of the preload settings? A: Preload settings determine which data types are loaded into memory when the system starts, balancing startup time and runtime performance.

Section sources

  • readme.md
  • init.py
  • hku_config_template.py

Getting Additional Help

When you encounter issues that cannot be resolved using this documentation, consider the following resources:

  1. Official Documentation: Refer to the comprehensive help documentation at https://hikyuu.readthedocs.io/

  2. Source Code: Examine the source code in the repository, particularly:

    • Error handling in hikyuu/util/mylog.py
    • Configuration templates in hikyuu/data/hku_config_template.py
    • Data import scripts in the hikyuu/data/ directory

  3. Community Support: Join the official WeChat group or QQ group mentioned in the README for community support.

  4. Issue Tracking: Report bugs or request features on the GitHub repository: https://github.com/fasiondog/hikyuu

  5. Donation and Priority Support: Consider the donation plan for priority support from the developer.

When seeking help, please provide:

  • The exact error message
  • Your operating system and Python version
  • The version of Hikyuu you are using
  • A minimal code example that reproduces the issue
  • Relevant log files (hikyuu.log and hikyuu_py.log from ~/.hikyuu/)

Section sources

  • readme.md
  • mylog.py
Add a custom footer
Add a custom sidebar

Clone this wiki locally