Troubleshooting Guide

This guide addresses common issues encountered while using sd-webui-infinite-image-browsing. When experiencing problems, always check the log.log file in the extension's root directory for detailed error messages, as these can provide crucial insights (scripts/iib/logger.py). For more general questions, refer to the README's FAQ↗.

1. Installation and Dependency Issues

Missing Optional Dependencies (hnswlib, numpy)

Problem: You might encounter errors indicating missing hnswlib or numpy when trying to use experimental features like "Natural Language Categorization & Search". Reason: These are powerful libraries for vector search and are optional. The core browsing functionality does not require them. The installation script (install.py) will skip them if IIB_SKIP_OPTIONAL_DEPS is set. Solution:

1. Install Manually: If you want to use the experimental features, ensure numpy and hnswlib are installed.
   If hnswlib fails to install, it often requires a C++ compiler. You can try installing pre-built wheels:

2. Skip Installation: If you do not need these experimental features, you can skip their installation by setting the environment variable IIB_SKIP_OPTIONAL_DEPS=1 before running pip install -r requirements.txt.
   • For detailed installation instructions, refer to the [Installation and Setup] wiki page.

2. Database and Indexing Issues

Database Path Migration

Problem: You have moved your image folders or the SD-webui installation, and the browser can no longer find images or the index is broken. Reason: The iib.db database stores absolute paths to your images. If these paths change, the database needs to be updated. The migrate.py script is designed for this. Solution:

1. Use migrate.py: Run the migrate.py script from the extension's root directory with the old and new base directories.
   • --db_path: Path to your iib.db file (default is iib.db in the extension root).
   • --old_dir: The base part of the path to be replaced.
   • --new_dir: The new base part of the path.
2. Rebuild Image Index (if migration fails or is partial): If images are still not found or search results are incorrect, proceed to rebuild the image index.

"No valid image directories" / "it appears that there is some issue"

Problem: The application starts but reports that it cannot find any image directories, or the image index is empty. Reason: The application cannot locate the configured image paths from your SD-webui config.json or any extra_paths you've provided. The app.py script includes paths_check to validate these. Solution:

1. Verify sd_webui_config: If running as a standalone app, ensure you've correctly specified the --sd_webui_config argument and that the path to your config.json is correct and accessible.
2. Check sd_webui_path_relative_to_config: If paths in your config.json are relative, ensure --sd_webui_path_relative_to_config is used.
3. Add extra_paths: If your images are in custom locations not covered by SD-webui's config, add them using the --extra_paths argument when launching app.py, or via the UI.
4. Update Image Index: After verifying paths, run the application with --update_image_index to force a re-scan.
   • For more details on these arguments, see the [Configuration] wiki page.

Index Expired / Incorrect Search Results

Problem: The UI shows "Index expired, updating automatically" or search results are outdated/incorrect. Reason: The application tracks the modification dates of scanned folders (folders table in iib.db). If a folder's content has changed (new images added, old ones deleted/modified), the index becomes stale (scripts/iib/db/datamodel.py). Solution:

1. Allow Automatic Update: Often, the "Index expired" message will trigger an automatic update. Let it complete.
2. Manually Update Index: Click the "Update index" button on the search page or restart the application with --update_image_index.
3. Rebuild Index: If automatic updates or manual updates don't fix it (e.g., after a major change or data corruption), rebuild the entire index:
   • Navigate to the "Image Search" tab in the UI.
   • Click the "Rebuild Image Index" button. This will clear all non-custom tags and re-scan from scratch (scripts/iib/db/update_image_data.py).
   • You can also trigger this via the API: POST /infinite_image_browsing/db/rebuild_index.

3. Performance Issues

Slow Browsing/Loading

Problem: Image grids load slowly, especially for videos, or thumbnails take a long time to appear. Reason: Generating thumbnails and video covers on demand can be CPU-intensive. Caching improves this. Solution:

1. Pre-generate Caches:
   • Image Thumbnails: Run app.py with --generate_image_cache and --generate_image_cache_size <size> (e.g., 512x512) to pre-generate thumbnails.
   • Video Covers: Run app.py with --generate_video_cover to pre-generate video cover images.
   • Use --gen_cache_verbose for detailed progress output during generation.
2. Configure Cache Directory: Ensure IIB_CACHE_DIR is set to a fast storage location (e.g., SSD). This can be configured in your .env file (scripts/iib/tool.py).
   • For more details, see the [Configuration] wiki page.

4. Access Control and Permissions

"User is not authorized to perform this action" / HTTP 401 / HTTP 403

Problem: You cannot access certain features, or the UI prompts for a "Secret Key". Reason: Access control is enabled (either automatically due to public exposure or explicitly configured), and the necessary authentication or file system permissions are not met. Solution:

1. Secret Key:
   • If prompted for a key, ensure you have set IIB_SECRET_KEY in your .env file and provide that key (scripts/iib/api.py).
   • If running in SD-webui with gradio-auth, a secret key is automatically required.
2. Access Control (IIB_ACCESS_CONTROL):
   • If you don't need access control, set IIB_ACCESS_CONTROL=disable in your .env file.
   • If you need it, ensure IIB_ACCESS_CONTROL=enable.
3. Permissions (IIB_ACCESS_CONTROL_PERMISSION):
   • Check if IIB_ACCESS_CONTROL_PERMISSION is set to read-only. If so, you won't be able to delete, move, or modify files. Change it to read-write if full access is desired (scripts/iib/api.py).
4. Allowed Paths (IIB_ACCESS_CONTROL_ALLOWED_PATHS):
   • Ensure that the paths you are trying to access are explicitly listed in IIB_ACCESS_CONTROL_ALLOWED_PATHS in your .env file (scripts/iib/api.py).
   • For more details on security configuration, refer to the [Configuration] wiki page.

5. AI/Topic Clustering Issues

"Topic clustering requires numpy+hnswlib"

Problem: When trying to use "Natural Language Categorization & Search", you get an error about missing numpy or hnswlib. Reason: These are mandatory Python dependencies for this experimental feature (scripts/iib/topic_cluster.py). Solution:

1. Install these dependencies as described in the [Installation and Setup] guide (Section 2.2).

"OpenAI API Key not configured" / HTTP 500 from AI API

Problem: AI features fail with an error about missing API key or base URL. Reason: The backend cannot connect to an OpenAI-compatible API for embeddings or chat completions (scripts/iib/api.py, scripts/iib/topic_cluster.py). Solution:

1. Configure Environment Variables: Set the following in your .env file:
   • OPENAI_API_KEY: Your API key.
   • OPENAI_BASE_URL: The endpoint URL for your OpenAI-compatible API.
   • AI_MODEL: Your preferred chat model.
   • EMBEDDING_MODEL: Your preferred embedding model.
   • TOPIC_TITLE_MODEL: (Optional) Specific model for topic titles.
2. Verify Network Access: Ensure your server has outbound internet access to the OPENAI_BASE_URL.

LLM Request Failures / "Chat API JSON extraction failed"

Problem: AI-powered features (like topic titling or tag graph abstraction) fail due to LLM response parsing errors. Reason: This can happen if the LLM returns malformed JSON, exceeds timeouts, or fails repeatedly (scripts/iib/topic_cluster.py, scripts/iib/tag_graph.py). Solution:

1. Check API Key/Base URL: Double-check these are correct and active.
2. Adjust LLM Parameters (Environment Variables): In your .env file, consider adjusting:
   • IIB_TAG_GRAPH_LLM_TIMEOUT_SEC: Increase the timeout if the API is slow.
   • IIB_TAG_GRAPH_LLM_MAX_ATTEMPTS: Increase the number of retries for transient network issues.
3. Review log.log: Detailed error messages from LLM interactions are logged here, including full response content if available, which can help diagnose specific API provider issues.

6. General UI/Application Errors

"element '#iib_top' is not found" / UI Fails to Load

Problem: The browser tab shows an error like "It seems to have failed to load. You can try refreshing the page." and mentions element '#iib_top' is not found. Reason: This usually indicates an issue with the Gradio UI not correctly rendering the extension's iframe or a JavaScript loading error (javascript/index.js). Solution:

1. Refresh Page: Perform a hard refresh of your browser (Ctrl+F5 or Cmd+Shift+R).
2. Check Browser Console: Open your browser's developer tools (usually F12) and check the "Console" tab for any JavaScript errors.
3. Reinstall Extension: If the issue persists, try reinstalling the extension from scratch.

"matched parser is not found"

Problem: Images are displayed but their generation information (prompts, metadata) cannot be retrieved or is incorrect. Reason: The application relies on parsers (scripts/iib/parsers/index.py) to extract metadata from different AI image formats (SD-webui, ComfyUI, Fooocus, etc.). If a file's metadata is missing, corrupted, or uses an unsupported format, parsing can fail. Solution:

1. Verify Image Metadata: Ensure the problematic image files actually contain generation metadata. Use external tools if necessary.
2. Check Parser Configuration:
   • For SD-webui Stealth PNGs, ensure IIB_ENABLE_SD_WEBUI_STEALTH_PARSER=true in your .env file if you expect to process such images.
   • For ComfyUI, IIB_COMFYUI_EXTRACT_ALL_PROMPTS=true might help with certain workflows.
3. Report Issue: If it's a standard image from a supported software and metadata is present, it might be a new metadata format. Report an issue with the image file (if possible) for investigation.

Application Crashes or Unexpected Behavior

Problem: The application stops working, closes unexpectedly, or behaves erratically. Reason: This could be due to various reasons, including unhandled exceptions, resource exhaustion, or conflicts. Solution:

1. Check log.log: Always refer to the log.log file in the extension's root directory (scripts/iib/logger.py). Python tracebacks and error messages will be recorded here, providing the most specific information for debugging.
2. Restart Application: A simple restart can often resolve transient issues.
3. Update/Reinstall: Ensure you are running the latest version of the extension. If issues persist, a clean reinstall might be necessary.
4. Resource Usage: Monitor your system's RAM and CPU usage. Very large image collections or extensive cache generation can consume significant resources.

---

For further assistance, please refer to the official FAQ or open an issue on the GitHub repository↗.