Troubleshoot ArtFlow

Start with a safe diagnosis

Do not repeat a failed batch immediately. First record:

• ArtFlow version
• Photoshop version
• active tab and action
• selected layer count and types
• the last useful log lines
• whether Preview was enabled
• whether the failure occurred before or after files were written

Use Copy in the Log toolbar. If clipboard access is unavailable, use Export to save the log or capture a screenshot with secrets hidden.

Nothing happens

Check for an active Photoshop document and a supported selection. Some actions require pixel or Smart Object layers; others operate on text, groups, or the full document.

Review advanced filters and hidden-layer settings. A valid selection can still produce zero candidates when every selected layer is filtered out.

Preview is empty or disappears

A preview belongs to the exact selection and options used to create it. Changing a field, filter, scope, or relevant layer state can invalidate it.

Run the action again. Do not apply an older proposal after changing its inputs.

AI Name reports a missing key

Open Settings, paste the Gemini key, and choose Save API. Confirm that a saved key is active. The value in an unsaved input is not necessarily the current runtime key.

If a stored key cannot be parsed, ArtFlow should fall back safely rather than breaking non-AI tools. Remove and save the affected key again.

Gemini quota is exhausted

A quota response may occur before the full visual export progress appears complete because requests and preparation can overlap by batch. ArtFlow stops remaining work when all available keys are known to be exhausted.

Check:

• selected model
• Google project and billing association
• free-tier availability for that model
• requests-per-minute and daily quota
• whether several saved keys belong to the same restricted project

Switching keys does not help when every key shares the same zero or exhausted quota.

TinyPNG fails

Confirm that the TinyPNG key was saved in the TinyPNG section, not the Gemini section. A successful save confirms local storage, not current service quota.

Use Local optimization when the network service is unavailable. Inspect the summary to distinguish TinyPNG success, local fallback, original retained, and actual error.

Export is blocked

For regular Export, verify output folder access, format compatibility, supported layer type, and non-empty bounds.

For PSD to Unity, run Scan again after changing structure or names. Resolve hard blockers such as invalid metadata, missing visible bounds, or invalid JSON inputs. Warnings may require a second confirmation click within the stated time window.

Unity output differs from Photoshop

Check:

1. source PSD bounds and visibility,
2. exported sprite dimensions and alpha,
3. role prefix and component child names,
4. anchor/stretch metadata,
5. 9-slice border,
6. Unity Canvas and reference resolution,
7. font mapping and TMP asset path.

Photoshop text rendering and Unity text rendering are not pixel-identical. Review wrapping, font fallback, and alignment separately from sprite placement.

Settings appear to persist incorrectly

ArtFlow intentionally stores language, presets, keys, and workflow choices across sessions. Installing an update should not erase user preferences.

Use individual controls to update a key or preset. Use Reset Settings only when a full reset is intended; confirmation requires a second action within the safety window, followed by a panel reload.

Recover from a bad action

1. Use ArtFlow Undo immediately when the action supports it.
2. Use Photoshop History if the document state is still available.
3. Close without saving only when you understand which later work will be lost.
4. Restore from the project’s normal PSD versioning or backup.

For support, provide the smallest reproducible PSD or sanitized structure that demonstrates the problem. Never include API keys in a report.