Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• src/main.rs
• static/script.js
• static/index.html
• static/style.css
• README.md
• Cargo.toml

This document provides guidance for diagnosing and resolving common issues within the hdrify application. It covers both client-side validation errors that occur in the user's browser and server-side processing errors that happen on the backend. The system is designed with clear error feedback loops to inform the user of any problems during the image upload and conversion process.

The troubleshooting process involves checking for errors reported in the UI, which originate from either client-side checks or messages passed from the server. For deeper issues, inspecting the server's console output is necessary, especially for problems related to the ImageMagick dependency.

Error Handling Architecture

The application has a two-layered validation and error handling system: one on the client (browser) and one on the server. The client-side handles initial input validation, while the server-side performs more robust checks and manages the core image processing logic.

This sequence diagram illustrates the complete flow from file upload to displaying the result, including potential failure points on both the client and server.

Client-Side Issues

Client-side errors are handled by static/script.js and are typically related to user input before any data is sent to the server. Errors are displayed in a dedicated error div at the bottom of the page.

Sources: static/script.js:369-373, static/index.html:77-79

Input Validation

Before uploading, the handleFile function in script.js performs two key validation checks.

This flowchart shows the client-side validation logic.

Check	Description	Error Message
File Type	Ensures the file is one of the supported MIME types: image/jpeg, image/png, or image/webp.	Unsupported file format: {type}. Please upload JPEG, PNG, or WebP images.
File Size	Ensures the file is no larger than 10MB (10 * 1024 * 1024 bytes).	File too large: {size}MB. Maximum size is 10MB.

Sources: static/script.js:157-179, static/index.html:29-31

Network and Server Response Errors

If client-side validation passes, an asynchronous fetch request is made to the /upload endpoint.

• Network Error: If the fetch call fails (e.g., server is down, no network), the catch block will trigger the error message: Network error: Could not connect to server.
• Server Error: If the server responds with { success: false, ... }, the message from the server's JSON response is displayed to the user. In both cases, the UI attempts to revert to the original uploaded image using the fallbackToOriginal() function.

Sources: static/script.js:284-292, static/script.js:294-301

Server-Side Issues

Server-side errors occur within the Rust backend after the client has sent a request. These are logged to the console where the server is running and a user-friendly message is sent back to the client.

Sources: src/main.rs

Request Validation

The handle_upload function in src/main.rs performs its own set of validations. This is a critical security and stability measure, as client-side checks can be bypassed.

This flowchart outlines the validation steps on the server.

The server validates the following:

1. Presence of Data: Checks that the image field in the form is not empty.
2. Base64 Decoding: Ensures the provided image data is a valid Base64 string.
3. File Size: Re-validates that the decoded image bytes do not exceed the 10MB limit.
4. Image Format: Checks the file's "magic bytes" to confirm it is a JPEG, PNG, or WebP file, rather than relying on a file extension or MIME type.

Sources: src/main.rs:28-70, src/main.rs:125-151

ImageMagick Processing Failures

The core functionality of hdrify depends on an external command-line tool, ImageMagick. The Rust backend executes magick in a subprocess.

Common failure points include:

• ImageMagick Not Installed: The server will fail to execute the command, resulting in a Failed to execute ImageMagick: ... error. Ensure ImageMagick is installed and its magick binary is in the system's PATH.
• ImageMagick Command Error: The magick command itself can fail (e.g., due to a corrupted image or invalid parameters). The backend captures stderr from the command and includes it in the error message: ImageMagick error: {error_msg}.
• Missing Profile: The command requires the 2020_profile.icc color profile. If this file is not accessible where the command is run, it may cause an error.

Sources: src/main.rs:85-123, README.md:35

Common Error Messages

The table below summarizes common errors, their origin, and potential solutions.

Error Message	Source	Cause	Resolution
Unsupported file format...	Client (script.js)	The selected file is not a JPEG, PNG, or WebP.	Upload a file with a supported format.
File too large: X.XMB. Maximum size is 10MB.	Client & Server	The image file exceeds the 10MB size limit.	Resize or compress the image before uploading.
Network error: Could not connect to server	Client (script.js)	The frontend cannot reach the backend server.	Ensure the backend server is running (cargo run) and accessible from the client. Check for network issues.
No image data provided	Server (main.rs)	The request to /upload was missing the image data. This is unlikely to happen with the standard UI.	This may indicate a problem with the client-side request creation or a manual API call.
Failed to decode image: ...	Server (main.rs)	The Base64 image data sent by the client was corrupted or invalid.	This is an unexpected error; try uploading the file again.
Unsupported image format...	Server (main.rs)	The server's magic byte check determined the file is not a valid JPEG, PNG, or WebP, even if the client accepted it.	Ensure the image file is not corrupted.
Failed to execute ImageMagick: ...	Server (main.rs)	The Rust backend could not find or run the magick command.	Install ImageMagick and ensure its binary is in the system's PATH. See README.md.
ImageMagick error: ...	Server (main.rs)	The magick command started but returned an error during processing.	Check the server logs for the specific error from ImageMagick. The image might be corrupt, or a required resource like 2020_profile.icc may be missing.

Sources: static/script.js:161-179, 289, src/main.rs:32, 41, 52, 63, 114, 120, README.md:35