Troubleshooting

Solutions to common issues when building with Refine. Fix connection problems, AI errors, and deployment issues.

Something not working? Find your issue below.

Connection Issues

Supabase connection fails

Symptoms:

"Failed to connect" error after OAuth
Tables not appearing in the Console
"Invalid API key" message

Fixes:

Check project status — Go to your Supabase dashboard. Make sure the project is active, not paused.
Verify permissions — When authorizing, ensure you granted access to the correct organization and project.
Try disconnecting and reconnecting — In Settings, remove the Supabase connection and add it again.
Check RLS policies — If tables appear but data doesn't load, your Row Level Security policies may be blocking access. Test with RLS temporarily disabled.

Tip

Supabase pauses free-tier projects after 7 days of inactivity. Resume your project in the Supabase dashboard.

REST API connection fails

Symptoms:

"Failed to fetch schema" error
"Network error" when testing endpoints
Data not loading in Preview

Fixes:

Check CORS settings — Your API must allow requests from refine.dev. Add these headers:

Access-Control-Allow-Origin: https://refine.dev
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Verify the API is accessible — Test your endpoint directly in a browser or with curl. If it requires auth, make sure the token is set in Secrets.
Check the schema format — Refine expects OpenAPI 3.0+ format. Swagger 2.0 works but may cause issues with complex schemas.
HTTPS required — Refine requires HTTPS endpoints. HTTP URLs will be rejected.

Don't expose admin-level API keys. Use read/write scoped tokens where possible.

"Network Error" in Preview

Symptoms:

Preview loads but API calls fail
Console shows CORS or network errors
Works locally but not in Refine

Fixes:

Check if API is public — Local APIs (localhost) won't work. Your backend must be accessible from the internet.
Verify secrets are set — Go to Settings and confirm your API keys are saved. Missing secrets cause silent failures.
Check API URL — Ensure the full URL is correct, including protocol (https://) and any path prefixes (/api/v1).

AI Generation Issues

AI generates wrong structure

Symptoms:

Table has wrong columns
Form fields don't match your data
Layout isn't what you expected

Fixes:

Be more specific — Instead of "create a users table", say "create a users table with columns: id, name, email, role, created_at"
Reference your data source — Tell the AI which table or endpoint to use: "Use the orders table from Supabase"
Describe the UI explicitly — "Show status as a colored badge" is better than "make status look nice"

→ See Prompting Guide for detailed examples.

AI doesn't understand my request

Symptoms:

Response doesn't match what you asked
AI asks for clarification repeatedly
Generated code is unrelated to your prompt

Fixes:

Break it down — Complex requests often fail. Ask for one thing at a time.
Use examples — "Like Stripe's dashboard" or "Similar to Notion's table view" helps the AI understand.
Attach a screenshot — Show what you're trying to achieve. Visual references work well.
Check your context — If you changed data sources mid-conversation, the AI might be confused. Start a new conversation.

AI keeps making the same mistake

Symptoms:

You've corrected the AI multiple times
It reverts to previous behavior
Changes don't stick

Fixes:

Rollback and retry — Use version history to go back to a working state, then try a clearer prompt.
Be specific about what's wrong — "Fix it" doesn't help. Say "The status badge colors are wrong. Use green for active, yellow for pending, red for cancelled."
Edit directly — For small fixes, use the Editor tab. It's faster and doesn't consume tokens.

Generated code has errors

Symptoms:

Preview shows error screen
TypeScript errors in Editor
App crashes on certain actions

Fixes:

Check the error message — The Preview error screen usually shows what went wrong.
Rollback — If a recent change broke things, use version history to go back.
Describe the error to the AI — Paste the error message in chat: "I'm getting this error: [error]. Fix it."
Check data types — Mismatched types (string vs number, null values) cause many runtime errors.

Preview Issues

Preview not updating

Symptoms:

Changes in Editor don't appear
Preview shows old version
Refresh doesn't help

Fixes:

Wait for save — The Editor auto-saves, but large changes take a moment.
Hard refresh — Use Cmd/Ctrl + Shift + R to force reload.
Check for errors — If there's a syntax error, the preview won't update. Check the Editor for red underlines.

Preview works but exported app doesn't

Symptoms:

Everything works in Refine
Exported app shows errors or blank screen
Data doesn't load in production

Fixes:

Set environment variables — Secrets from Refine aren't included in exports. Create a .env file or set them in your hosting platform.
Check CORS — Your production domain needs to be allowed by your API. Update CORS settings.
Verify API URLs — If you used relative URLs or localhost anywhere, they won't work in production.

→ See Publish & Export for the full checklist.

Token Issues

Running out of tokens quickly

Symptoms:

Token balance drops fast
Hit limit before finishing your app

Fixes:

Write better prompts — Detailed first prompts save iterations. Spend 30 seconds on a clear prompt instead of 5 rounds of "fix this."
Use the Editor — Small changes (colors, text, spacing) don't need AI. Edit directly.
Batch changes — Instead of 3 separate requests, combine: "Change header to blue, add padding to cards, and increase font size."

→ See Prompting Guide for token-saving tips.

Token count seems wrong

Symptoms:

More tokens used than expected
Simple requests use many tokens

Fixes:

Complex requests cost more — Generating a full dashboard uses more tokens than adding a column.
Iterations add up — Each message consumes tokens. Five "make it better" requests cost more than one detailed prompt.
Check your plan — Free tier has 300 tokens. Pro has 1,500. Confirm your plan in account settings.

Export Issues (Pro)

Hosting build fails

Symptoms:

Build fails when deploying exported code
Error messages in hosting platform logs

Fixes:

Check build logs — Your hosting platform shows what failed. Common causes:
- Missing environment variables
- TypeScript errors
- Dependency conflicts
Set environment variables — Add all your secrets with VITE_ prefix in your hosting platform's settings.
Test locally first — Run pnpm install && pnpm build locally to see detailed errors before deploying.

Downloaded project won't run

Symptoms:

pnpm install fails
pnpm dev shows errors
App doesn't start

Fixes:

Check Node version — Requires Node 18+. Run node --version to check.

Delete node_modules and reinstall:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Create .env file — Secrets aren't included. Create .env with your API keys:
```
VITE_SUPABASE_URL=your_url
VITE_SUPABASE_ANON_KEY=your_key
```
Check for TypeScript errors — Run pnpm build to see all errors.

Still Stuck?

If your issue isn't listed here:

Check the error message — Most errors include helpful context.
Try a fresh project — Start new to see if the issue is project-specific.
Describe the problem clearly — What you tried, what happened, what you expected.
Contact support — Reach out via the app or email with details.

Next Steps

Prompting Guide — Get better results from the AI
Using the Console — Master the workspace
Publish & Export — Ship your application

Troubleshooting

On this page