Troubleshooting

This guide covers common issues and their solutions.

Installation Issues

"API key not found"

Cause: Missing or invalid API key configuration.

Solution:

Check that .env.local exists in the project root
Verify you have at least one provider API key configured
Restart the development server after editing
Ensure no extra spaces or quotes around the key

.env.local

# At least one of these is required
GEMINI_API_KEY=AIza...
REPLICATE_API_TOKEN=r8_...
FAL_KEY=...

Port 3000 in use

Cause: Another application is using the default port.

Solution:

# Use a different port
npm run dev -- -p 3001

Or find and stop the process using port 3000.

Dependencies fail to install

Cause: Node.js version mismatch or network issues.

Solution:

Verify Node.js version: node --version (should be 18+)
Clear npm cache: npm cache clean --force
Delete node_modules and package-lock.json
Run npm install again

Generation Issues

"No image generated" / Empty output

Possible causes:

API quota exceeded
Invalid or blocked content in prompt
Network timeout

Solutions:

Check Google AI Studio for quota status
Simplify your prompt
Check browser console for detailed errors
Try again (temporary API issues)

Generation takes too long

Cause: Large images, complex prompts, or API congestion.

Solutions:

Use faster models for testing (check model descriptions for speed info)
Reduce resolution setting
Check provider status pages for outages
For video generation, note that processing can take several minutes

Poor quality output

Solutions:

Write more detailed prompts
Try different models — each has different strengths
Provide better reference images
Increase resolution
Experiment with model-specific parameters

"Content blocked" error

Cause: The AI flagged content as potentially violating usage policies.

Solution:

Modify your prompt to avoid restricted content
Ensure reference images comply with policies
Try rephrasing your request

Connection Issues

Can't connect nodes

Cause: Incompatible handle types.

Remember:

Text outputs → Text inputs only
Image outputs → Image inputs only
You can't mix types

Connection disappears

Cause: Invalid connection removed automatically.

Solution: Check that source and target handles are compatible types.

Data not flowing through

Possible causes:

Edge is paused (dashed line)
Upstream node hasn't run
Connection is to wrong handle

Solutions:

Click edge to unpause if paused
Run the full workflow
Verify connection endpoints

Canvas Issues

Nodes disappeared

Possible causes:

Zoomed out too far
Panned away from nodes

Solutions:

Use minimap to locate nodes
Press keyboard shortcut to fit view
Check if nodes were accidentally deleted

Can't select nodes

Cause: Selection area or click might be hitting background.

Solution: Try clicking directly on node content, not edges.

Canvas is laggy

Possible causes:

Too many nodes
Large images loaded
Browser memory pressure

Solutions:

Remove unused nodes
Use smaller preview images
Refresh the page
Close other browser tabs

Save/Load Issues

Workflow won't save

Possible causes:

Browser permissions
Invalid file path
Disk full

Solutions:

Check browser download permissions
Try saving to a different location
Check available disk space

Loaded workflow has missing data

Cause: Workflow was saved from a different version or with incompatible settings.

Solutions:

Check if all expected nodes loaded
Re-add missing connections
Re-input any missing data

Auto-save not working

Possible causes:

Auto-save disabled
No project path configured
Storage permission issues

Solutions:

Enable auto-save in settings
Configure a valid project path
Check browser storage permissions

Browser-Specific Issues

Works in Chrome but not Safari/Firefox

Chrome is the recommended browser. Other browsers may have compatibility issues during early development.

Solution: Use Chrome for the most stable experience.

Images not displaying

Possible causes:

CORS issues
Invalid image data
Memory limits

Solutions:

Check browser console for errors
Try with smaller images
Refresh the page

API Issues

Rate limiting

Symptoms: Errors about too many requests.

Solutions:

Wait a few minutes before retrying
Reduce batch size
Space out generation requests

API errors (500, 503)

Cause: Server-side issues at Google/OpenAI.

Solutions:

Check API status pages
Wait and retry
Report persistent issues

Provider-Specific Issues

Replicate errors

"Model not found": The model may have been removed or renamed. Use the model search dialog to find current models.

Slow generation: Some Replicate models run on cold-start hardware. First generations may take longer.

Rate limiting: Replicate has per-account rate limits. Space out requests or upgrade your plan.

fal.ai errors

"Invalid API key": Verify your FAL_KEY is correct in .env.local. Keys are case-sensitive.

Timeout errors: Some models (especially video) may exceed default timeouts. The app includes extended timeout support for video generation.

Video generation issues

Video won't play: Ensure the output is connected to an Output node, which supports video playback.

Generation timeout: Video generation can take several minutes. The app uses a 10-minute timeout for video models.

Format not supported: Some video formats may not play in all browsers. Chrome has the best compatibility.

Getting More Help

Check the Console

Open browser developer tools (F12 or Cmd+Option+I) and check:

Console tab: JavaScript errors and logs
Network tab: Failed API requests
Application tab: Storage issues

Report Bugs

If you've found a bug:

Note the exact steps to reproduce
Copy any error messages
Take a screenshot if helpful
Open an issue on GitHub (opens in a new tab)

Community Support

Join the Discord community for:

Real-time help from other users
Tips and workflow sharing
Feature discussions

Best Practices Changelog