Troubleshooting

This guide covers common issues you might encounter while using PhantomWP and how to resolve them.

Connection Issues

"Disconnected" Status

Symptoms: Header shows "Disconnected" with a red dot. Buttons are disabled.

Solutions:

1. Wait a moment - reconnection is automatic
2. Refresh the page if it doesn't reconnect within 30 seconds
3. Check the Codespace - it may have stopped:
   • Go to github.com/codespaces
   • Find your Codespace and restart it
4. Check your internet connection

"Connecting" Status Stuck

Symptoms: Shows "Connecting" with orange dot for more than a minute.

Solutions:

1. Refresh the page
2. Check if the Codespace is running in GitHub
3. Try a different browser - Chrome or Edge recommended
4. Clear browser cache and cookies

Codespace Won't Start

Symptoms: Codespace stays in "Starting" state or shows an error in GitHub.

Solutions:

1. Wait longer - first-time starts can take 3-5 minutes
2. Check GitHub status at githubstatus.com
3. Delete and recreate the Codespace:
   • Go to github.com/codespaces
   • Delete the stuck Codespace
   • Return to PhantomWP and create a new one

"Codespace Limit Reached"

Symptoms: Can't create new Codespaces in PhantomWP.

Solutions:

1. Go to github.com/codespaces
2. Delete Codespaces you're not using
3. Return to PhantomWP and try again

GitHub free tier includes limited Codespace hours per month.

Service Status Issues

Astro Dev Server Stopped

Symptoms: Services panel shows Astro as "stopped". Preview doesn't load.

Solutions:

1. Click the Services icon in the header
2. Click Restart Services
3. Wait 10-15 seconds for the server to start
4. Refresh the preview

Preview Not Loading

Symptoms: Preview pane is blank, shows loading forever, or shows error.

Solutions:

1. Check service status - click the Activity icon in the header
2. Restart services if they show as stopped
3. Wait for startup - servers take 10-15 seconds after Codespace starts
4. Refresh the preview using the refresh button
5. Check for build errors - syntax errors prevent the server from starting

Preview Shows Build Error

Symptoms: Error message in preview instead of your page.

Solutions:

1. Read the error message - it usually points to the problem
2. Check recent changes - undo your last edit
3. Common causes:
   • Missing closing tags in Astro/HTML
   • Invalid frontmatter syntax (check --- blocks)
   • Import errors (file doesn't exist)
   • TypeScript errors

File and Editor Issues

Changes Not Saving

Symptoms: File shows unsaved indicator (dot on tab) but Save doesn't work.

Solutions:

1. Check connection status - must be "Connected"
2. Press Cmd/Ctrl + S to manually save
3. Check for errors in the file that might prevent saving
4. Refresh the page if the WebSocket disconnected

File Tree Not Updating

Symptoms: New files don't appear, deleted files still show.

Solutions:

1. Wait a moment - file tree updates automatically
2. Click a different folder and back
3. Refresh the page to reload the file tree

Search Not Finding Files

Symptoms: File tree search returns no results for files you know exist.

Solutions:

1. Check the exact filename - search is case-sensitive
2. Check if file is ignored - some files are hidden by default
3. Toggle "Show All Files" if you need to see config files

WordPress Issues

Connection Failed

Symptoms: Error when testing WordPress connection.

Solutions:

1. Check the URL format:
   • Include https://
   • No trailing slash
   • Just the domain (not /wp-admin)
2. Test the REST API directly:
   • Visit https://yoursite.com/wp-json/wp/v2/posts
   • Should show JSON, not an error page
3. Check security plugins - some block the REST API
4. Verify WordPress version - REST API requires WordPress 4.7+

No Content Found

Symptoms: Connected successfully but shows 0 posts or pages.

Solutions:

1. Check post status - only "Published" content appears
2. Check visibility - private/password-protected posts are hidden
3. Test the API manually: https://yoursite.com/wp-json/wp/v2/posts?status=publish

Generate Pages Fails

Symptoms: Error when clicking "Generate Pages" in WordPress modal.

Solutions:

1. Check connection status - must be "Connected"
2. Select at least one content type (Posts, Pages, etc.)
3. Check for existing files - you'll be asked before overwriting
4. Wait for completion - large sites take longer

Media Download Slow

Symptoms: Downloading WordPress media takes a very long time.

Solutions:

1. This is normal for large libraries - downloading hundreds of images takes time
2. Download in batches if possible
3. Skip media download and use remote URLs instead (configured in astro.config.mjs)

AI Assistant Issues

"No API Keys" Message

Symptoms: AI says no API keys configured, or model dropdown is empty.

Solutions:

1. Open AI Settings (gear icon in chat panel)
2. Add an API key for at least one provider:
   • Anthropic (for Claude models)
   • OpenAI (for GPT models)
   • Google (for Gemini models)
3. Verify the key is valid with your provider

AI Not Responding

Symptoms: Sent a message but nothing happens, or stuck loading.

Solutions:

1. Check your API key is valid and has credits
2. Try a different model - one provider might be down
3. Refresh the page and try again
4. Check rate limits with your AI provider

Tool Call Failed

Symptoms: AI tried to create/modify a file but it failed.

Solutions:

1. Check the error message in the tool call card
2. Verify connection status - must be "Connected"
3. Check file permissions - some files are protected
4. Try the operation manually to see if there's an issue

Inline AI Not Appearing

Symptoms: Keyboard shortcut doesn't open the inline AI widget.

Solutions:

1. Check you have API keys configured in AI Settings
2. Verify the shortcut:
   • AI Modify: Cmd/Ctrl + Shift + M
   • AI Generate: Cmd/Ctrl + Shift + G
3. Make sure editor is focused - click in the editor first
4. Try right-click context menu instead

Media Manager Issues

Upload Failed

Symptoms: Image upload shows error or nothing happens.

Solutions:

1. Check connection status - must be "Connected"
2. Verify file type - only images are supported in src/media/
3. Check file size - very large images may timeout
4. Try uploading one file at a time

Images Not Showing in Media Library

Symptoms: Uploaded images don't appear in the grid.

Solutions:

1. Wait a moment - previews load asynchronously
2. Refresh the Media Manager (close and reopen)
3. Check src/media/ folder in file tree

Drag to Editor Not Working

Symptoms: Dragging image from file tree doesn't insert code.

Solutions:

1. Drag from src/media/ - only this folder supports drag-to-editor
2. Have a file open in the editor
3. Position your cursor where you want the code
4. Try right-click > Insert at Cursor instead

Menu Builder Issues

Menus Not Appearing on Site

Symptoms: Built a menu but it doesn't show in preview.

Solutions:

1. Save the menu after making changes
2. Check the menu component is imported in your layout
3. Verify the menu file was created in src/components/
4. Refresh the preview after saving

WordPress Menus Not Loading

Symptoms: "Import from WordPress" shows no menus.

Solutions:

1. Connect WordPress first via the WordPress modal
2. Check WordPress has menus - create one in Appearance > Menus
3. Verify REST API access to your WordPress site

Component Library Issues

Components Not Inserting

Symptoms: Click Insert but nothing happens.

Solutions:

1. Have a file open in the editor
2. Position your cursor where you want the component
3. Check the file type - components insert into .astro files
4. Check for multi-select mode - may need to click Insert for selection

Preview Not Showing in Library

Symptoms: Component previews are blank.

Solutions:

1. Wait for previews to load - they're rendered live
2. Check internet connection - previews need network access
3. Try a different component - some may have issues

Deployment Issues

"You need to add a Login Connection"

Symptoms: Deploying shows an error like "Failed to link [repo]. You need to add a Login Connection to your GitHub account first."

Solutions:

1. Go to Vercel Authentication Settings
2. Connect your GitHub account
3. Return to PhantomWP and try deploying again

This happens when your Vercel account is not connected to GitHub. Even with a valid Vercel API token, Vercel needs a separate GitHub connection to access your repository.

Vercel Connection Failed

Symptoms: Can't connect Vercel account.

Solutions:

1. Check you're logged into Vercel
2. Authorize PhantomWP when prompted
3. Try a different browser if popup is blocked

Deployment Stuck

Symptoms: Deployment shows "Building" for a long time.

Solutions:

1. Check Vercel dashboard for detailed build logs
2. Common build issues:
   • Missing dependencies in package.json
   • Syntax errors in code
   • Missing environment variables
3. Cancel and redeploy if it seems stuck

Site Not Updating After Deploy

Symptoms: Deployed but live site shows old content.

Solutions:

1. Wait a few minutes - CDN cache takes time to clear
2. Hard refresh your browser: Cmd/Ctrl + Shift + R
3. Check Vercel dashboard - verify deployment completed
4. Check you pushed your changes before deploying

Getting Help

If your issue isn't listed here:

Check Other Documentation

• IDE Overview
• WordPress Connection
• Deployment Guide

Report an Issue

1. Note what you were trying to do
2. Copy any error messages
3. Note your browser and OS
4. Contact support with this information

Quick Reference