Troubleshooting

Sharp / Native Module Issues

Sharp installation fails

Sharp requires native bindings. If npm install fails:

# macOS - ensure Xcode Command Line Tools
xcode-select --install

# Linux - install libvips
# Debian/Ubuntu
sudo apt-get install libvips-dev

# Alpine (Docker)
apk add vips-dev build-base python3 make g++

"Cannot find module 'sharp'"

Rebuild Sharp for your platform:

npm rebuild sharp

Docker Issues

Out of memory during build

The build stage compiles Sharp. Increase Docker memory:

docker build --memory=2g -t repix .

Health check fails

Ensure /health is accessible. Check logs:

docker logs <container-id>

Verify the app listens on the expected port (default 3210).

Image Fetch Errors

"Invalid source" (hostname_not_allowed)

The image URL hostname is not allowed by your configuration.

• Add the hostname to SOURCE_HOSTNAME (comma-separated list)
• Or set SOURCE_PREFIX to a custom base URL that includes the hostname

"Source not found" (source_not_found)

The source URL returned an error (e.g. 404) or could not be fetched.

• Verify the source URL is publicly accessible
• Check SOURCE_PREFIX (default https://)
• Ensure the URL in the path doesn't include https:// (Repix adds it)
• Increase FETCH_TIMEOUT for slow origins

"Invalid image format"

The source file may be corrupted or not a supported format (JPEG, PNG, WebP, AVIF, GIF).

"Image too large"

Dimensions exceed IMAGE_MAX_WIDTH or IMAGE_MAX_HEIGHT. Adjust in .env.

403 Custom Transformations Not Allowed

When ALLOW_CUSTOM_TRANSFORMS is false, only preset names work. Use presets from your PRESETS env var:

/thumbnail/example.com/photo.jpg

Custom params like w=400 will return 403.