How to Troubleshoot Issues with awesome-gpt-image-2: A Complete Diagnostic Guide

Most failures in awesome-gpt-image-2 stem from invalid APIMart API keys, insufficient credits, rate limiting, or browser storage restrictions, all of which can be diagnosed through the browser console and network tab.

awesome-gpt-image-2 is a single-page React application that enables users to browse GPT-Image 2 prompts and generate images directly in the browser. Because the app operates entirely client-side, most issues arise from API authentication problems, network failures, or local storage constraints that can be traced through specific error codes in src/apimartClient.js and shared/apimart.js.

Understanding the Three-Layer Architecture

To effectively troubleshoot, you must understand the separation of concerns across the codebase:

• UI Layer (src/main.jsx, src/community.jsx): Renders the gallery and handles user interactions, including API key input and generation status display.
• Generation Engine (src/apimartClient.js, shared/apimart.js): Manages all communication with the APIMart endpoints at https://api.apimart.ai, including task submission and polling.
• Auth & Persistence (src/supabaseClient.js): Handles optional Supabase authentication for platform-credit mode and persists API keys in localStorage.

All network traffic flows through the APIMart client, making src/apimartClient.js the primary source of error logging.

Diagnosing Common Error Codes

The application surfaces specific error codes that map to distinct failure modes. Use these to pinpoint your issue immediately.

APIMART_API_KEY_INVALID

This error indicates a malformed or revoked personal key. The client validates keys using verifyPersonalApimartKey in src/apimartClient.js.

Check your key format in the API-Key settings panel (gear icon). Valid keys must be plain strings under 512 characters with no line breaks. Run this verification in the browser console:

JSON.parse(localStorage.getItem('gpt-image-2-apimart-key:v1'))

If the value is null or contains whitespace, clear it using localStorage.removeItem('gpt-image-2-apimart-key:v1') and re-enter the key.

APIMART_BALANCE_REQUIRED

Your APIMart account has exhausted its credits. This error bubbles up from submitPersonalGeneration and displays as apimartBalanceRequired in the UI. Navigate to your APIMart dashboard to top-up your balance; no code changes are required.

APIMART_RATE_LIMITED

The server returns a Retry-After header when you exceed request quotas. The client's retryAfterMilliseconds helper in shared/apimart.js converts this to a wait time. Reduce your generation frequency or implement exponential backoff in your polling logic.

APIMART_UNAVAILABLE

HTTP 5xx responses from /v1/models or /v1/images/generations indicate an APIMart service outage. Verify the API status externally or implement a circuit breaker in your polling logic.

APIMART_REQUEST_REJECTED

Prompts violating moderation policies trigger this error with error.code: 'moderation'. The UI shows apimartRequestRejected. Edit your prompt to remove prohibited content and resubmit.

Task Timeout

The pollApimartTask function stops polling after maxAttempts is exceeded (configurable in the options parameter). If tasks consistently timeout, increase maxAttempts or verify that your prompts generate images quickly enough on the APIMart platform.

Storage Failures

When saveStoredApimartKey or browserStorage in src/apimartClient.js fail, they surface apimartStorageFailed. This typically occurs in private browsing modes where localStorage is disabled. Enable local storage or use a non-private browsing window.

Environment and Configuration Issues

Missing Supabase Environment Variables

Platform-credit mode requires VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY. If isSupabaseConfigured in src/supabaseClient.js returns false, the sign-in UI hides and the app falls back to personal-key mode. Create a .env file in the project root based on .env.example and populate these Vite environment variables before building.

Expired Image URLs

Generated images carry an expires_at timestamp. The normalizeApimartExpiry function in shared/apimart.js normalizes this, but if the URL expires before the UI renders it, the image displays as "task timeout". Save results immediately using saveGeneratedTest to cache them locally before expiry.

Step-by-Step Debugging Workflow

Follow this sequence to isolate issues systematically:

1. Open the browser console and filter for messages from apimartClient.js (e.g., responseError).
2. Inspect stored credentials by running the localStorage inspection command above.
3. Monitor the Network tab to ensure requests target https://api.apimart.ai/v1/... with the correct Authorization: Bearer <token> header.
4. Validate your build environment by checking that import.meta.env.VITE_GA_MEASUREMENT_ID, VITE_SUPABASE_URL, and VITE_SUPABASE_ANON_KEY are injected (verify in vite.config.js).
5. Execute the test suite by running npm test to verify client logic against the assertions in src/apimartClient.test.js.

Code Examples for Common Fixes

Verify a Personal APIMart Key

import { verifyPersonalApimartKey } from './apimartClient';

// Returns a promise that resolves true if the key is valid.
await verifyPersonalApimartKey('my-apimart-key')
  .then(() => console.log('Key works!'))
  .catch(err => console.error('Invalid key:', err.code));

Source: src/apimartClient.js – verifyPersonalApimartKey

Submit a Generation with Personal Key

import { submitPersonalGeneration } from './apimartClient';

// Prompt must be < 10,000 chars.
const { taskId } = await submitPersonalGeneration(
  'a futuristic city skyline at sunset',
  'my-apimart-key',
  'en'
);
console.log('Submitted task:', taskId);

Source: src/apimartClient.js – submitPersonalGeneration

Poll a Task Until Completion

import { pollApimartTask } from './apimartClient';

const finalTask = await pollApimartTask(
  () => fetchPersonalTask(taskId, 'my-apimart-key', 'en'),
  { maxAttempts: 12, intervalMs: 2000 }
);

console.log('Image URL:', finalTask.image);

Source: src/apimartClient.js – pollApimartTask

Cache Generated Images Locally

import { saveGeneratedTest, getSavedGeneration } from './apimartClient';

// Save after generation
saveGeneratedTest(42, {
  image: finalTask.image,
  savedAt: new Date().toISOString(),
  expiresAt: finalTask.expiresAt
});

// Retrieve later (only if not expired)
const saved = getSavedGeneration(42, localStorage, Date.now());
if (saved) console.log('Cached image:', saved.image);

Source: src/apimartClient.js – saveGeneratedTest / getSavedGeneration

Detect Authentication Mode

import { getStoredApimartKey, apimartPersonalMode, apimartPlatformMode } from './apimartClient';

const key = getStoredApimartKey();
if (key) {
  console.log(apimartPersonalMode(maskApimartKey(key), APIMART_DEFAULT_PRICE_USD));
} else {
  console.log(apimartPlatformMode);
}

Source: src/main.jsx – UI strings for mode selection

Summary

• Authentication errors (APIMART_API_KEY_INVALID) require verifying the key format in localStorage or using verifyPersonalApimartKey.
• Credit and rate limits (APIMART_BALANCE_REQUIRED, APIMART_RATE_LIMITED) must be resolved through the APIMart dashboard or by reducing request frequency.
• Storage failures indicate private browsing mode or disabled localStorage; switch to a standard browser window.
• Missing Supabase variables hide the platform-credit UI; add VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY to your .env file.
• Polling timeouts can be mitigated by increasing maxAttempts in the pollApimartTask options.

Frequently Asked Questions

Why is my APIMart API key not working despite being correct?

Your key may contain hidden characters or exceed 512 characters. Use verifyPersonalApimartKey to test it programmatically, or manually inspect localStorage.getItem('gpt-image-2-apimart-key:v1') in the console to ensure no line breaks or whitespace exist.

How do I fix rate limiting errors when generating multiple images?

The server returns a Retry-After header that the client converts via retryAfterMilliseconds in shared/apimart.js. Wait for the specified duration before retrying, or adjust your pollApimartTask configuration to use longer intervalMs between status checks.

Why are my generated images not displaying after successful generation?

The image URL likely expired before rendering. APIMart URLs include an expires_at timestamp processed by normalizeApimartExpiry. Save results immediately using saveGeneratedTest to cache them in localStorage, or increase the polling frequency to fetch the result faster.

How do I enable platform-credit mode with Supabase?

Ensure VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are defined in your environment variables and accessible via import.meta.env. If isSupabaseConfigured in src/supabaseClient.js is false, the UI defaults to personal-key mode. Restart your Vite dev server after adding these variables to .env.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}