Troubleshooting Guide & FAQ - Ktiseos-Nyx/Dataset-Tools GitHub Wiki

Welcome to the Dataset-Tools Troubleshooting Guide and Frequently Asked Questions. If you're encountering an issue or have a question, please check here first!

Installation Issues

Q: I'm on Linux (Ubuntu/Debian) and pip install . fails with errors related to PyQt6, Qt6, or qmake. A: This usually means the necessary Qt6 development system libraries are missing. Please refer to our detailed guide: Advanced: Installing PyQt6 System Dependencies on Older Linux (Link to the wiki page you created for this).

Q: Python is installed, but the dataset-tools command isn't found after pip install .. A:

  1. Ensure your virtual environment is active: If you installed Dataset-Tools in a virtual environment (recommended!), make sure it's activated in your current terminal session.
  2. Check your PATH: When Python packages with command-line entry points are installed, the directory containing these executables must be in your system's PATH environment variable.
    • For global installs (not recommended), this is usually handled by Python's installer.
    • For virtual environments, activating the environment typically adds its bin or Scripts directory to the PATH.
    • You can check where Python is installing scripts by running python -m site --user-base (for user installs) or checking your venv's Scripts (Windows) or bin (macOS/Linux) folder. Ensure this location is in your PATH.
  3. Reinstall: Try reinstalling the package: pip uninstall dataset-tools then pip install . again within the correct environment.

Q: I'm having trouble with git clone. A: Ensure Git is correctly installed on your system. Refer to the Requirements page for Git installation links. You might also be encountering network issues or typos in the repository URL. The correct URL is https://github.com/Ktiseos-Nyx/Dataset-Tools.git.

Application Usage Issues

Q: I clicked the "Open Folder" button, but no files are showing up. A:

  1. Check File Types: Dataset-Tools currently supports specific image formats (like PNG, JPG, WEBP), text files (.txt, .caption), and .safetensors files. Ensure your folder contains these types of files. See the Supported File Formats & Metadata Details page for more info.
  2. Permissions: Make sure Dataset-Tools has permission to read the folder and its contents.
  3. Subfolders: Currently, Dataset-Tools primarily scans the selected folder and does not recursively scan subfolders for display in the main list. (Clarify if this is still true or if subfolder scanning is a feature).

Q: The application window is too small/large or elements look strange. A:

  1. Window Sizing Settings: Check the "Settings" menu for "Window Sizing" options. You might be able to select a preset or have the application remember your preferred size.
  2. Display Scaling: If you're using display scaling in your operating system (e.g., 125%, 150%), some Qt applications can occasionally have minor visual quirks. Try resetting scaling to 100% to see if it resolves the issue, or experiment with Qt environment variables related to scaling (advanced).
  3. Themes: Try switching themes in the "Settings" menu. A different theme might render better on your system.

Q: Metadata for my images isn't showing up, or it looks incomplete. A:

  1. Supported Metadata: Dataset-Tools is designed to parse common AI-generated metadata (e.g., from A1111, ComfyUI workflows embedded in PNGs, Civitai metadata) and safetensors metadata. If your images were generated by a different tool or have non-standard metadata, it might not be fully displayed. See Understanding AI Metadata and Supported File Formats & Metadata Details.
  2. File Corruption: The image file itself might be corrupted, or the metadata might be malformed.
  3. Recent Updates: If you recently updated Dataset-Tools, there might have been changes to metadata parsing. Ensure you have the latest version.

Q: The application feels slow when I open a folder with many thousands of files. A: Dataset-Tools is continuously being optimized. For very large folders:

  1. Patience: Initial loading and thumbnail generation (if/when implemented more broadly) can take time.
  2. Hardware: Performance can be impacted by your system's CPU speed and disk I/O speed.
  3. Consider breaking up extremely large collections into smaller, more manageable subfolders if practical for your workflow.

Q: How do I reset Dataset-Tools settings to default? A: Dataset-Tools may store its settings in a configuration file. The location is typically: * Windows: C:\Users\<YourUsername>\AppData\Local\Ktiseos-Nyx\Dataset-Tools or C:\Users\<YourUsername>\AppData\Roaming\Ktiseos-Nyx\Dataset-Tools * macOS: ~/Library/Application Support/Ktiseos-Nyx/Dataset-Tools or ~/Library/Preferences/Ktiseos-Nyx/Dataset-Tools * Linux: ~/.config/Ktiseos-Nyx/Dataset-Tools or ~/.local/share/Ktiseos-Nyx/Dataset-Tools Deleting the configuration files/folder (while the application is closed) will usually reset settings. (Verify this path or if there's an in-app reset option)

Q: Where can I find error logs? A: When Dataset-Tools is run from a terminal, any error messages or tracebacks will typically be printed directly to the terminal output. This is the best place to look for detailed error information.

Feature Questions

Q: Does Dataset-Tools support [specific file format/metadata type]? A: Please check our Supported File Formats & Metadata Details page for a comprehensive list.

Q: Can I edit metadata directly within Dataset-Tools? A: Currently, Dataset-Tools is primarily a viewer for metadata. Direct editing capabilities are not a core feature at this time but may be considered for future development. (Adjust if editing is planned/implemented).

Q: How does the drag-and-drop feature work? A: You can drag a single image file from your system's file explorer onto the main Dataset-Tools window. The application will then load and display the contents of the folder where that image is located.

Still Need Help?

If your issue isn't covered here or you need further assistance:

  1. Check the GitHub Issues to see if someone else has reported a similar problem.
  2. Consider joining our Discord Server to ask the community.
  3. If it's a new bug or a specific unaddressed issue, please create a new issue on GitHub, providing as much detail as possible (your OS, Dataset-Tools version, steps to reproduce, error messages).