Skip to content

Commit 5b6da1b

Browse files
danielandreassondanielandreasson
authored
Merge pull request #116 from lovablelabs/daniel/troubleshooting-page-update
fix to troubleshooting page, slop removed and page improved
2 parents 3ef558e + c2185d2 commit 5b6da1b

File tree

1 file changed

+31
-228
lines changed

1 file changed

+31
-228
lines changed

‎tips-tricks/troubleshooting.mdx‎

Lines changed: 31 additions & 228 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ description: "Actionable steps to resolve issues in your development lifecycle."
44
icon: "toolbox"
55
---
66

7-
## "Try to Fix" error loops
7+
## Build errors
88

9-
Building with Lovable makes coding faster and more intuitive—but even the best AI development tools can occasionally hit a snag. Sometimes your code won't run as expected, or you might notice unexpected behavior where the AI interprets your intent incorrectly.
9+
Building with Lovable makes coding faster and more intuitive, but even the best AI development tools can occasionally hit a snag. Sometimes your code won't run as expected, or you might notice unexpected behavior where the AI interprets your intent incorrectly.
1010

1111
Here's a step-by-step guide to help you navigate issues and get back on track:
1212

@@ -17,278 +17,81 @@ Here's a step-by-step guide to help you navigate issues and get back on track:
1717
Click the **Try to Fix** button when an error shows up. Lovable will scan your logs, detect the issue, and attempt a quick fix. It's your fastest first move. If that doesn't work, it's time to dig deeper.
1818
</Step>
1919
<Step title="Diagnose Unexpected Behavior">
20-
Your code may run without errors but not behave as intended. That's **unexpected behavior**—harder to spot and harder to fix. Try this:
20+
Your code may run without errors but not behave as intended. That's **unexpected behavior**, harder to spot and harder to fix. Try this:
2121

22-
- **Review your original prompt** to confirm your instructions.
23-
- **Break it down**: Check individual components and logic.
24-
- **Add visuals**: Use screenshots to clarify what went wrong.
22+
- **Revert and re‑prompt**: Roll back to just before the issue occurred, then try a clearer, revised prompt.
2523
</Step>
2624
<Step title="Write More Effective Prompts">
2725
Clear, structured prompts lead to better results. Use this format:
2826

29-
1. **Project Overview** – What are you building?
30-
2. **Page Structure** – List key pages/components.
31-
3. **Navigation Logic** – Describe user flow.
32-
4. **Visual Aids** – Upload wireframes or screenshots.
33-
5. **Implementation Steps** – Lay out the build order.
27+
1. **Use Chat Mode** and ask, "Can you outline the steps or plan for this feature?"
28+
2. **Review the plan** that Lovable suggests, ask for changes or clarifications if needed.
29+
3. **Prompt Lovable**: "Now, let's build this step by step."
3430
</Step>
3531
<Step title="Build in Logical Order">
3632
Structure matters. Follow this recommended flow:
3733

3834
1. Create layout and pages.
39-
2. Connect Supabase or your backend.
35+
2. Connect to Lovable Cloud or an external Supabase connection.
4036
3. Set up authentication and user roles.
4137
4. Plan and organize feature logic.
4238
5. Prompt Lovable to implement features.
4339
</Step>
44-
<Step title="Use Chat Mode for Clarity">
45-
When unsure, switch to **Chat Mode**:
46-
47-
- Ask Lovable to **analyze your project state**.
48-
- Request a **recap of attempted solutions**.
49-
- Prompt for **new directions** to solve persistent problems.
50-
</Step>
51-
<Step title="If You're Still Stuck: Advanced Tactics">
52-
Still no luck? Try this:
53-
54-
- **Be exact** – Describe the bug and your expectations clearly.
55-
- **Use images** – Screenshots or videos help illustrate problems.
56-
- **Ask directly** – "What else can we try?"
57-
- **Rollback** – Restore to a working version and rebuild incrementally.
58-
</Step>
5940
</Steps>
6041

61-
## What's Going Wrong? Common Troubleshooting Areas
62-
63-
Troubleshooting generally falls into these categories:
64-
65-
1. **UI or Layout Glitches**
66-
2. **API or Backend Issues**
67-
3. **Prompt Misinterpretations**
68-
4. **AI Unresponsiveness or Misbehavior**
69-
5. **Platform or Integration Errors**
70-
71-
Use the accordions below to identify specific issues and actions:
72-
7342
### General issues
7443

7544
<AccordionGroup>
76-
<Accordion title="Need a fast diagnosis?">
77-
Jump into Chat-Only Mode and type: "Something's off. Can you walk me through what's happening and what you've tried?"
45+
<Accordion title="Need some quick help?">
46+
Jump into Chat-Only Mode and type: "This specific function is not working. Can you walk me through what's happening and what you've tried?"
7847
</Accordion>
7948
<Accordion title="UI or Layout Problems">
80-
- Check component hierarchy and styles.
81-
- Use screenshots to explain visual bugs.
82-
- Prompt Lovable with: "Why is this element misaligned? Fix it."
49+
- Provide screenshots of the UI issue directly to the AI for a clearer diagnosis.
50+
- Use the Edit tool to select and highlight specific UI features you want to change, then describe the adjustment you want.
51+
- For example: "See the highlighted element? Center it vertically and increase padding."
8352
</Accordion>
8453
<Accordion title="When completely stuck">
8554
- Prompt: "Take a step back. Analyze the error and suggest a different approach."
8655
- Break the task into smaller parts.
8756
- Use the revert button if errors persist.
8857
</Accordion>
89-
<Accordion title="Code sandbox error">
90-
This should not happen. Please report it to the support team.
91-
</Accordion>
9258
<Accordion title="Not found preview or spinning up sandbox">
93-
Try a hard refresh. If unresolved, contact support.
94-
</Accordion>
95-
</AccordionGroup>
96-
97-
### AI Reliability
98-
99-
<AccordionGroup>
100-
<Accordion title="Avoiding AI mistakes in prompt engineering">
101-
- Keep prompts clear and structured.
102-
- Use reverse meta prompting.
103-
- Test in Chat-Only Mode before applying big changes.
104-
</Accordion>
105-
<Accordion title="AI not responding">
106-
This shouldn't happen. Please report it to the support team.
107-
</Accordion>
108-
<Accordion title="Persistent Fix error loops">
109-
Adjust your prompt to help the AI understand your goal or ask for step-by-step debugging help.
110-
</Accordion>
111-
<Accordion title="Refactor broke everything">
112-
Make small, incremental changes. If the issue persists, roll back to a stable version or debug in chat.
113-
</Accordion>
114-
<Accordion title="Error loops, hallucinations, or broken logic">
115-
Revert to a stable version and provide more context in your next prompt. Use visual editor or attach a knowledge file.
116-
</Accordion>
117-
<Accordion title="AI not doing changes">
118-
The AI might be editing the wrong files or misinterpreting. Be very specific or edit manually.
119-
</Accordion>
120-
<Accordion title="Chat mode not responding or incomplete">
121-
This was fixed by engineering. Please report if it happens again.
122-
</Accordion>
123-
<Accordion title="Unexpected Crashes, Errors, or Loops">
124-
- Don't retry the same prompt. Simplify or rephrase.
125-
- Ask: "What fixes have we already tried?"
126-
- Rebuild from a previous working state.
59+
Issues with the preview not found or the sandbox spinning up can be related to either the sandbox environment or your connection.
60+
Sandbox problems are often temporary, try a hard refresh first. If this continues, it may indicate a broken sync with GitHub or a connection issue.
61+
For persistent issues, review our [GitHub integration guide](https://docs.lovable.dev/integrations/github).
12762
</Accordion>
12863
</AccordionGroup>
12964

13065
### Core functionalities
13166

13267
<AccordionGroup>
13368
<Accordion title="Preview is white">
134-
- Likely a runtime error. Check browser console logs.
135-
- Use chat to troubleshoot.
136-
- Try a hard refresh or revert.
137-
</Accordion>
138-
<Accordion title="Rollback fails">
139-
Report to the support team if you can't revert your project.
69+
- These are often the result of issues in the vite.config.ts file or that security headers have been introduced into the project.
70+
- Build errors or syntax errors in the code
71+
- JavaScript runtime errors causing crashes
72+
- Missing dependencies or broken components
73+
- Authentication or routing issues blocking the page
74+
75+
To troubleshoot: Ask Lovable to review the vite.config.ts file or remove security headers.
76+
Check browser console for errors, restore to an earlier version, or ask Lovable to investigate the blank screen issue.
14077
</Accordion>
14178
<Accordion title="Unpublish or deactivate projects">
14279
You can unpublish or delete your project in Project Settings.
14380
</Accordion>
144-
<Accordion title="Kicked out of project">
145-
This issue has been resolved. Report it if it recurs.
146-
</Accordion>
147-
<Accordion title="Remix doesn't work (no Supabase connection)">
148-
Shouldn't happen. Contact support.
149-
</Accordion>
150-
<Accordion title="Loading profile error">
151-
Shouldn't happen. Report to the support team.
152-
</Accordion>
153-
<Accordion title="Email unsubscribe not working">
154-
This is a serious issue likely related to our email provider. Contact support immediately.
155-
</Accordion>
156-
<Accordion title="Unexpected logout or access loss">
157-
Reach out to support directly.
158-
</Accordion>
159-
<Accordion title="Challenges with larger projects">
160-
- Break up large changes into smaller steps.
161-
- Restart your browser if it slows down.
162-
- If it persists, report your use case to support.
163-
</Accordion>
164-
</AccordionGroup>
165-
166-
### Supabase issues
167-
168-
<AccordionGroup>
16981
<Accordion title="Error with Edge Functions">
170-
- **l Scope:** Use the principle of least privilege for all credentials
171-
172-
When using Lovable with Supabase, always store sensitive API keys as Supabase Edge Function secrets rather than environment variables or in source code.
173-
</Accordion>
174-
<Accordion title="Setting Environment Variables">
175-
Double-check syntax and variable names. See the [Supabase docs](https://supabase.com/docs).
176-
</Accordion>
177-
<Accordion title="Supabase connection is lost">
178-
Disconnect and reconnect. Might be caused by an integration update.
179-
</Accordion>
180-
<Accordion title="Remix does not work with Supabase">
181-
Remixing is blocked for Supabase-connected projects for security reasons.
82+
Check the Cloud tab -> Logs for specific error messages. Verify all required secrets and environment variables are properly configured.
83+
Try redeploying by making a small change to the edge function code by prompting Lovable. Ensure your database connection is working.
84+
Ask Lovable to investigate the specific error and fix any issues found in the logs.
18285
</Accordion>
18386
<Accordion title="Project not found">
184-
Please report to support.
185-
</Accordion>
186-
<Accordion title="HTTP Fetch failures">
187-
Usually means a backend server isn't responding. Use chat mode to debug.
188-
</Accordion>
189-
<Accordion title="Connecting Supabase">
190-
To connect your Lovable project to Supabase:
191-
192-
1. Click the Supabase menu in the top right of the editor
193-
2. Select "Connect to Supabase"
194-
3. Follow the prompts to connect to your Supabase project
195-
4. Once connected, Lovable can see your tables, RLS policies, and functions
196-
</Accordion>
197-
</AccordionGroup>
198-
199-
### GitHub issues
200-
201-
<AccordionGroup>
202-
<Accordion title="Can't push to GitHub">
203-
You may have deleted your repo. [Restore it here](https://docs.github.com/en/repositories/creating-and-managing-repositories/restoring-a-deleted-repository).
204-
</Accordion>
205-
<Accordion title="Branches are broken">
206-
Branch switching is experimental. Use at your own risk.
207-
208-
Once connected to GitHub, you can work with different branches:
209-
210-
#### **Branch Switching Steps**
211-
212-
```
213-
# To switch from main to dev:
214-
1. In Dev Mode, open the Git panel
215-
2. Select the branch dropdown
216-
3. Choose "dev" or click "Create new branch" if it doesn't exist
217-
4. Your workspace will update to reflect the selected branch
218-
```
219-
220-
<Note>
221-
Switching branches will change all files in your workspace to match that branch.
222-
</Note>
223-
#### **Branch Management:**
224-
225-
- **Create a new branch:** Click "Create new branch" in the Git panel
226-
- **Delete a branch:** Use the GitHub interface (not available directly in Lovable)
227-
- **Default branch:** Set in GitHub repository settings
228-
229-
If you can't switch branches:
230-
231-
- Commit or stash any uncommitted changes
232-
- Check if you have untracked files that would be overwritten
233-
- Try refreshing the Lovable editor
234-
</Accordion>
235-
<Accordion title="Repository sync issues">
236-
- Check your [GitHub permissions](https://docs.lovable.dev/integrations/git-integration).
237-
- Use rollback to undo unwanted changes.
238-
</Accordion>
239-
<Accordion title="Deleted repository, now nothing works">
240-
[Restore your GitHub repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/restoring-a-deleted-repository).
241-
</Accordion>
242-
<Accordion title="Connecting GitHub">
243-
To connect your Lovable project to GitHub:
244-
245-
1. Click the GitHub button in the top right of the editor
246-
2. Authorize Lovable to access your GitHub account
247-
3. Choose whether to create a new repository or use an existing one
248-
4. Follow the prompts to complete the connection
249-
250-
#### **Repository Access Levels:**
251-
252-
When connecting Lovable to GitHub, you can choose different access levels:
253-
254-
- **All repositories:** Access to all your GitHub repositories
255-
- **Only select repositories:** Choose specific repositories to connect
256-
257-
<Info>
258-
Lovable uses GitHub's OAuth flow for secure authentication. You can revoke access anytime from your GitHub account settings.
259-
</Info>
260-
</Accordion>
261-
<Accordion title="Authentication Issues">
262-
If you're having trouble with GitHub authentication:
263-
264-
- Reconnect your GitHub account in Lovable
265-
- Check if your GitHub access token has expired
266-
- Verify you have the necessary permissions for the repository
267-
- Ensure two-factor authentication isn't blocking access
268-
</Accordion>
269-
<Accordion title="Failed Pushes">
270-
If your push is rejected:
271-
272-
1. Pull the latest changes from the remote repository
273-
2. Resolve any conflicts
274-
3. Try pushing again
275-
4. If still failing, check if the branch is protected
276-
</Accordion>
277-
<Accordion title="Branches are broken">
278-
This is an experimental feature. Expect occasional instability.
279-
</Accordion>
280-
<Accordion title="Deleted your repository">
281-
[Restore your GitHub repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/restoring-a-deleted-repository).
87+
This usually means the project was deleted. If you didn't delete it on purpose, please reach out to support for help restoring your project.
28288
</Accordion>
28389
</AccordionGroup>
28490

28591
### Need more help?
28692

28793
Still stuck? Try this:
28894

289-
1. Use [Chat Mode](https://lovable.dev/chat) for step-by-step help.
290-
2. If you're a paid customer, contact [Support](https://lovable.dev/support).
291-
292-
## Comprehensive Debugging Manual
293-
294-
[This document](https://docs.google.com/document/d/1dfIy5rtkPN9Zi4smX1VAbfbhAiEyBvVw8p7B8kJiEVs/edit?tab=t.0) or [this website](https://kb-lovable.netlify.app/?tab=errors#errors) were written by a Lovable power user in our Discord community.
95+
1. Use chat mode for step-by-step help.
96+
2. If it's an issue with the UI or a feature, revert back to a stable state.
97+
3. If you're a paid customer and want to report a platform-wide issue, contact [Support](https://lovable.dev/support).

0 commit comments

Comments
 (0)