Troubleshooting

Relevant source files

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

• App.tsx
• services/hfService.ts
• README.md
• components/SettingsModal.tsx
• translations.ts
• types.ts
• package.json

This document provides guidance for diagnosing and resolving common issues encountered within the Peinture AI Image Gen application. It covers error handling mechanisms, API communication failures, local state problems, and setup issues. All information is derived directly from the application's source code.

Error Handling Architecture

The application employs a centralized error handling strategy within the main App component. Errors originating from asynchronous operations, such as API calls, are caught and propagated to the UI through a dedicated state variable.

Sources: App.tsx:88, App.tsx:184-192

Core Components

• error State: A state variable const [error, setError] = useState<string | null>(null); in App.tsx holds the current error message string. When this state is not null, the UI displays an error message.
  Sources: App.tsx:88, App.tsx:647-652
• Service Layer (hfService.ts): Functions that interact with external APIs (generateImage, upscaler, optimizePrompt) use try...catch blocks. On failure, they log the error and re-throw it to be caught by the calling function in App.tsx.
  Sources: services/hfService.ts:133-136, services/hfService.ts:163-166, services/hfService.ts:186-189
• UI Display: The App.tsx component conditionally renders an error block when the error state is populated. This block displays an AlertCircle icon and the error message from the state.
  Sources: App.tsx:647-652

Error Handling Flow

The following diagram illustrates how an error from an API call is processed and displayed to the user.

Common Errors and Solutions

Error Message (UI)	Likely Cause	Recommended Action	Source Files
Generation Failed	The daily quota for the public Hugging Face API has been exhausted.	Add a personal Hugging Face Read Token in the Settings modal.	services/hfService.ts:90-93
Generation Failed	Network connectivity issue or the Hugging Face service is down.	Check your internet connection and verify the status of the Hugging Face Spaces endpoints.	services/hfService.ts:134
Failed to optimize prompt.	The text.pollinations.ai service is unavailable or returned an error.	Try generating the image without prompt optimization or try again later.	App.tsx:280-282
Failed to upscale image.	The upscaler service is unavailable or the input image URL is no longer valid.	Try upscaling again. If it persists, the service may be down.	App.tsx:226-228
Image does not download, opens in a new tab instead.	The image is hosted on a domain with strict CORS policies that prevent direct fetching, and the canvas fallback also failed.	This is the last resort behavior. Right-click the image in the new tab to save it.	App.tsx:432-434

Hugging Face Quota Error

A specific error is thrown by the service layer if the API response indicates a quota issue.

The following sequence diagram shows the interaction when a quota error occurs.

Local State and Data Persistence

The application uses the browser's localStorage to persist user settings and generated image history. Issues can arise if this data becomes corrupted or is manually cleared.

Sources: App.tsx:93-104, App.tsx:129-131, components/SettingsModal.tsx:21-23

Local Storage Keys

Key	Purpose	Management	Source Files
ai_image_gen_history	Stores an array of GeneratedImage objects.	Images older than 24 hours are filtered out on initial load. The array is updated whenever a new image is generated, upscaled, or deleted.	App.tsx:93-104, App.tsx:133-135
huggingFaceToken	Stores the user-provided Hugging Face API token.	Set and saved via the Settings modal. Read by getAuthHeaders in hfService.ts for API requests.	components/SettingsModal.tsx:25-27
app_language	Stores the selected language ('en' or 'zh').	Set on initial load based on browser language and persisted on change.	App.tsx:44-48, App.tsx:125-127

To debug local state issues, use your browser's developer tools to inspect the values stored under these keys in localStorage.

History Expiration Logic

On application startup, the image history is loaded from localStorage. A filter is applied to remove any images that are more than one day old, which can be a source of confusion if users expect history to be permanent.

// App.tsx:93-104
const [history, setHistory] = useState<GeneratedImage[]>(() => {
  try {
    const saved = localStorage.getItem('ai_image_gen_history');
    if (!saved) return [];
    
    const parsedHistory: GeneratedImage[] = JSON.parse(saved);
    const now = Date.now();
    const oneDayInMs = 24 * 60 * 60 * 1000;
    
    // Filter out images older than 1 day
    return parsedHistory.filter(img => (now - img.timestamp) < oneDayInMs);
  } catch (e) {
    console.error("Failed to load history", e);
    return [];
  }
});

Sources: App.tsx:93-104

Installation and Environment

Problems can occur during the initial setup of the development environment.

Prerequisites

Ensure the following are installed, as specified in the project documentation:

• Node.js: Version 18 or higher.
• Package Manager: npm, yarn, or pnpm.

Sources: README.md:32-34

Dependency Installation

If the application fails to start, first ensure all dependencies are correctly installed by running npm install in the project root. The required dependencies are listed in package.json.

Sources: README.md:39-42, package.json:9-14

Deployment

When deploying the application as a static site, a common issue for Single Page Applications (SPAs) is improper handling of client-side routing. The web server must be configured to redirect all 404 "Not Found" requests back to index.html. This allows the React application to handle the route.

Sources: README.md:83-85