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

Having trouble? You're in the right place. This guide covers the most common questions and issues. Please check here for a solution before opening a new issue.

1. Quick Fixes

For many common application glitches, one of these simple steps will often resolve it:

  1. Restart the Application: Close Dataset-Tools completely and open it again.
  2. Update to the Latest Version:
    • If you are running from source, make sure you have the latest main branch.
    • If you installed via pip, ensure you have the latest version installed.

2. Installation Issues

Q: I installed the tool, but the dataset-tools command isn't found. A: This almost always means the command is not in your system's PATH.

  • Solution (for Developers): Make sure your Python virtual environment is active. Activating the environment automatically adds the correct directory to your PATH. If it's active and still not found, try reinstalling the package (pip install .) within the active environment.

Q: I'm having trouble with git clone. A: Make sure Git is installed correctly on your system. The correct repository URL is https://github.com/Ktiseos-Nyx/Dataset-Tools.git.

Q: On Linux, pip install fails with errors about PyQt6, qmake, or xcb. A: This is a common issue on Linux systems (especially older Debian/Ubuntu versions) where required system development libraries are missing. Please read the detailed guide below.

Detailed Guide: Fixing PyQt6 Build Issues on Linux

Audience: Developers using Linux who see errors mentioning PyQt6 could not be built, or that qmake is missing.

Background: When you install dependencies, pip tries to download a pre-built "wheel" of PyQt6. If one isn't available for your specific Linux version/architecture, pip tries to build it from source. This fails if you don't have the Qt6 development tools installed.

Step 1: Install System-Level Qt6 Development Packages You need to install the necessary tools via your package manager.

  • Debian/Ubuntu-based systems:

    sudo apt update
sudo apt install qt6-base-dev qt6-tools-dev

    (If those specific packages aren't found, try sudo apt install qt6-default).

  • Other Distributions (Fedora, Arch, etc.): Use your package manager (dnf, pacman) to search for and install the equivalent Qt6 development packages.

Step 2: Retry the Python Dependency Installation Once system packages are installed, return to your project directory (with your virtual environment activated) and try again:

  • Using uv: uv pip install -r requirements.txt
  • Using pip: pip install -r requirements.txt

Step 3: Advanced Troubleshooting for qmake If it still fails saying qmake cannot be found, it might be installed in a location not in your PATH.

  1. Find qmake: Run which qt6-qmake. (Example output: /usr/lib/qt6/bin/qt6-qmake).
  2. Add to PATH: Add the directory containing the executable to your PATH for the current session. 
    export PATH="/usr/lib/qt6/bin:$PATH"
    (Replace /usr/lib/qt6/bin with the actual path from step 1).
  3. Retry: Run the install command again in the same terminal.

3. Common Usage Problems

Q: I opened a folder, but no files are listed. A: Check the following:

  1. Correct File Types: Make sure the folder contains supported files (PNG, JPG, WebP, Safetensors). See our Supported File Formats page.
  2. Permissions: Ensure the application has permission to read the folder contents.
  3. Subfolders: The tool scans the selected folder but does not currently search for files in subfolders recursively.

Q: The metadata panel is empty or incomplete. A: This usually happens for one of two reasons:

  1. Unsupported Format: The metadata was saved by a tool we don't parse yet. Our support is strongest for A1111, ComfyUI, and Civitai data.
  2. No Metadata: The image file may not contain any embedded metadata.

Q: The application window is too big/small or elements look blurry. A: This is often related to display scaling.

  • Solution: Try switching themes in the Settings menu. If that doesn't work, try adjusting the display scaling settings in your operating system (e.g., setting it to 100% temporarily to test).

Q: The app is slow when opening a folder with thousands of files. A: Opening a directory with a massive number of files takes time, especially on slower hard drives.

  • Workaround: We recommend working with smaller, more focused datasets or subfolders for the best performance.

Q: How do I reset the application's settings? A: You can reset settings by deleting the configuration folder. Make sure the application is closed first.

  • Windows: C:\Users\<YourUsername>\AppData\Local\Ktiseos-Nyx
  • macOS: ~/Library/Application Support/Ktiseos-Nyx
  • Linux: ~/.config/Ktiseos-Nyx

4. Feature Questions

Q: Can I edit image metadata in this tool? A: Yes, but with limitations:

  • You can currently only edit metadata for PNG files.
  • Editing is focused on the text chunks used by popular generators (A1111, ComfyUI).
  • We do not yet support editing general-purpose XMP or EXIF data (like that from Midjourney).

Q: How does the drag-and-drop feature work? A: If you drag a single image file from your file explorer onto the main window, the application will open the folder containing that image.

Q: Does the tool automatically associate text files with images? A: No. The tool can view the contents of .txt and .json files, but you must select the file itself. It does not automatically link image.txt to image.png.

Still Need Help?

If your question wasn't answered here, please:

  1. Check the GitHub Issues to see if your problem has already been reported.
  2. Join our Discord Server to ask the community for help.
  3. If it's a new bug, please create a new issue with as much detail as possible.