Troubleshooting

This guide helps you diagnose and fix common problems with AI Image Renamer CLI.

Quick Diagnosis

Run this checklist to identify issues:

bash

# 1. Check Python version
python3 --version  # Should be 3.8+

# 2. Check if tool is installed
rename-images --version  # Should show version

# 3. Check API key
echo $GROQ_API_KEY  # Should show your key (starts with gsk_)

# 4. Test with a known-good image
rename-images path/to/test-image.jpg

Installation Issues

"command not found: rename-images"

Symptoms:

bash

$ rename-images photo.jpg
zsh: command not found: rename-images

Causes & Solutions:

Cause 1: Not installed

bash

# Check if installed
pip show ai-image-renamer

# If not found, install it
pip install ai-image-renamer

Cause 2: Wrong PATH (user installation)

If you installed with pip install --user, the command may not be in your PATH.

bash

# Find where pip installed it
pip show ai-image-renamer | grep Location
# Example: Location: /Users/you/.local/lib/python3.11/site-packages

# The binary is in the bin subdirectory
# Add to PATH (for zsh):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Cause 3: Virtual environment not activated

If you installed in a virtual environment, activate it first:

bash

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
# or
.\venv\Scripts\activate   # Windows

# Then run the command
rename-images photo.jpg

Cause 4: Multiple Python versions

You might have installed for one Python version but are running another.

bash

# Check which Python pip uses
pip --version

# Install for the correct Python
python3 -m pip install ai-image-renamer

"Permission denied"

Symptoms:

bash

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied

Solution: Use user installation

bash

pip install --user ai-image-renamer

Alternative: Use a virtual environment

bash

python3 -m venv venv
source venv/bin/activate
pip install ai-image-renamer

"Requirement already satisfied" but doesn't work

Symptoms:

bash

$ pip install ai-image-renamer
Requirement already satisfied: ai-image-renamer in ./venv/lib/...

$ rename-images
command not found

Solution: Reinstall

bash

pip uninstall ai-image-renamer
pip install ai-image-renamer

API Key Issues

"GROQ_API_KEY environment variable is not set"

Symptoms:

bash

$ rename-images photo.jpg
RuntimeError: GROQ_API_KEY environment variable is not set.

Solution 1: Set in shell configuration

bash

# For Zsh (default on macOS)
echo 'export GROQ_API_KEY="gsk_your-key-here"' >> ~/.zshrc
source ~/.zshrc

# For Bash
echo 'export GROQ_API_KEY="gsk_your-key-here"' >> ~/.bashrc
source ~/.bashrc

Solution 2: Use .env file

bash

# Create .env in current directory
echo 'GROQ_API_KEY="gsk_your-key-here"' > .env

Solution 3: Set inline (temporary)

bash

GROQ_API_KEY="gsk_your-key-here" rename-images photo.jpg

"Invalid API key"

Symptoms:

bash

groq.AuthenticationError: Invalid API Key

Solutions:

Verify your key is correct (starts with gsk_)

Check for extra spaces or quotes:

bash

# Wrong
export GROQ_API_KEY='"gsk_xxx"'

# Correct
export GROQ_API_KEY="gsk_xxx"

Generate a new key at console.groq.com/keys

Image Processing Issues

"Skipping invalid image file"

Symptoms:

bash

$ rename-images document.pdf
Skipping invalid image file: document.pdf

Cause: File isn't a supported image

The tool only processes actual image files. Check:

bash

# Verify file type
file your-file.jpg

# Expected output:
# your-file.jpg: JPEG image data, JFIF standard 1.01, ...

# If it says something else, the file isn't that type

Common issues:

File claims to be	Actually is
`image.jpg`	PNG renamed to .jpg
`photo.png`	WebP file
`picture.jpg`	Corrupted file
`scan.jpg`	PDF document

Solution:

Use correct file extensions
Verify file isn't corrupted
Check the file opens in an image viewer

"Failed to retrieve content from image"

Symptoms:

bash

$ rename-images photo.jpg
Processing photo.jpg...
Failed to retrieve content from image: photo.jpg

Cause: API returned empty response

Solutions:

Check API status: Visit status.groq.com
Wait and retry: Temporary API issues
Check rate limits: You may have hit Groq's rate limits
Try different image: Some images may not be processable

"Generated filename too short, skipping"

Symptoms:

bash

$ rename-images abstract.jpg
Processing abstract.jpg...
Generated filename too short, skipping: abstract.jpg

Cause: AI description was mostly non-alphabetic

This happens when the AI returns a description that becomes empty after sanitization (e.g., "123 456 !!!").

Solutions:

Try with more words: rename-images -w 10 photo.jpg
The image content may not be suitable for description
Retry — AI responses vary

File not renamed (no output)

Symptoms:

bash

$ rename-images photo.jpg
$ # No output at all

Cause: File doesn't exist

The tool silently skips non-existent files.

Solution:

bash

# Check file exists
ls -la photo.jpg

Network Issues

Connection timeouts

Symptoms:

bash

requests.exceptions.Timeout: HTTPSConnectionPool(host='api.groq.com', port=443): Read timed out.

Solutions:

Check internet connection
Try again (temporary network issue)
Large images may take longer — use smaller files if possible

SSL certificate errors

Symptoms:

bash

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED]

Solutions:

Update Python's certificates:

bash

# macOS (if using python.org installer)
/Applications/Python\ 3.11/Install\ Certificates.command

Update certifi:
bash
```
pip install --upgrade certifi
```

Rate Limiting

"Rate limit exceeded"

Symptoms:

bash

groq.RateLimitError: Rate limit exceeded

Cause: Too many API requests

Groq's free tier has limits:

30 requests per minute
7,000 tokens per minute

Solutions:

Wait and retry: Limits reset after 1 minute
Process fewer files at once

Add delays between batches:

bash

# Process 20 files, wait, process 20 more
rename-images *.jpg | head -20
sleep 60
rename-images *.jpg | tail -n +21

Performance Issues

Processing is slow

Expected performance: 100-500ms per image (network + AI)

If significantly slower:

Large images: Resize before processing

bash

# Resize large images first
convert large.jpg -resize 1920x1080 large-resized.jpg
rename-images large-resized.jpg

Network issues: Check your internet speed
API latency: Groq may be experiencing load

Getting Help

Check Logs

Run with verbose output:

bash

rename-images photo.jpg 2>&1 | tee debug.log

Verify Environment

bash

# Check all prerequisites
echo "Python: $(python3 --version)"
echo "pip: $(pip --version)"
echo "Package: $(pip show ai-image-renamer | grep Version)"
echo "API Key: ${GROQ_API_KEY:0:7}..."

Report Issues

If you've tried everything and still have problems:

Search existing issues
Open a new issue with:
- Python version (python3 --version)
- Package version (rename-images --version)
- Operating system
- Full error message
- Steps to reproduce

Troubleshooting ​

Quick Diagnosis ​

Installation Issues ​

"command not found: rename-images" ​

Cause 1: Not installed ​

Cause 2: Wrong PATH (user installation) ​

Cause 3: Virtual environment not activated ​

Cause 4: Multiple Python versions ​

"Permission denied" ​

"Requirement already satisfied" but doesn't work ​

API Key Issues ​

"GROQ_API_KEY environment variable is not set" ​

"Invalid API key" ​

Image Processing Issues ​

"Skipping invalid image file" ​

"Failed to retrieve content from image" ​

"Generated filename too short, skipping" ​

File not renamed (no output) ​

Network Issues ​

Connection timeouts ​

SSL certificate errors ​

Rate Limiting ​

"Rate limit exceeded" ​

Performance Issues ​

Processing is slow ​

Getting Help ​

Check Logs ​

Verify Environment ​

Report Issues ​

Troubleshooting

Quick Diagnosis

Installation Issues

"command not found: rename-images"

Cause 1: Not installed

Cause 2: Wrong PATH (user installation)

Cause 3: Virtual environment not activated

Cause 4: Multiple Python versions

"Permission denied"

"Requirement already satisfied" but doesn't work

API Key Issues

"GROQ_API_KEY environment variable is not set"

"Invalid API key"

Image Processing Issues

"Skipping invalid image file"

"Failed to retrieve content from image"

"Generated filename too short, skipping"

File not renamed (no output)

Network Issues

Connection timeouts

SSL certificate errors

Rate Limiting

"Rate limit exceeded"

Performance Issues

Processing is slow

Getting Help

Check Logs

Verify Environment

Report Issues