Runtime Troubleshooting

This section provides solutions for common issues encountered while using Udility Diffuser. Most runtime errors stem from API configuration, dependency mismatches, or malformed SVG generation from the underlying LLM.

API and Configuration Errors

EnvironmentError: "The OpenRouter API key is not set"

This error occurs if the library cannot find the OPENROUTER_API_KEY in your system environment variables. Udility requires this key to communicate with the Meta Llama-3.5 models via OpenRouter.

Solution: Ensure you set the environment variable before calling diffuser functions:

import os
os.environ['OPENROUTER_API_KEY'] = 'your_api_key_here'

# Alternatively, verify it is set in your terminal
# echo $OPENROUTER_API_KEY

RuntimeError: "Failed to get detailed instructions"

This usually indicates an issue with the OpenRouter service, an invalid API key, or lack of credits/quota on your OpenRouter account.

Checklist:

Connectivity: Ensure your environment has outbound HTTPS access to https://openrouter.ai.
Quota: Check your OpenRouter Dashboard to ensure your key is active and has sufficient credits.
Model Availability: The model nousresearch/hermes-3-llama-3.1-405b must be accessible to your account.

SVG Generation and Parsing Errors

RuntimeError: "Failed to convert SVG to PNG"

This error occurs during the svg_to_png phase. It is typically caused by one of two things:

Malformed SVG Code: Occasionally, the LLM may return SVG code containing syntax errors or unexpected text outside the <svg> tags.
Missing System Dependencies: cairosvg (the engine behind the conversion) relies on cairo, a system-level library.

Solution for Missing Dependencies (Linux/Ubuntu/Colab): If you see errors related to libcairo, install the system dependencies:

sudo apt-get install python3-dev libffi-dev libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libglib2.0-0 shared-mime-info

Solution for Malformed SVG: If the error persists, try re-running the command. Since the model is generative, a second attempt often produces a cleaner SVG script.

Display and Visualization Issues

RuntimeError: "Failed to display image"

This error occurs in the display_image function when matplotlib or Pillow cannot open or render the generated file.

Common Scenarios:

Headless Environments: If you are running the script on a remote server without a GUI, plt.show() may fail.
- Workaround: Access the output.png file directly from the local directory instead of relying on the built-in display function.
File Permissions: Ensure the script has write permissions in the working directory to save the output.png.

Images not appearing in Jupyter/Colab

If the code executes without error but no image appears:

Ensure you have %matplotlib inline set if using older Jupyter environments.
Check if output.png was created in your file sidebar.

Dependency Conflicts

If you encounter ImportError or AttributeError after installation, ensure your dependencies meet the following requirements:

Fixing Conflicts:

pip install --upgrade openai cairosvg Pillow matplotlib

Summary of Internal Error Handlers

While you interact primarily with generate_image_from_text, the library uses internal functions that may surface in stack traces:

get_detailed_instructions: Handles the initial prompt expansion.
generate_svg_from_instructions: Handles the actual code generation.
svg_to_png: Handles the conversion logic via cairosvg.