Troubleshooting

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

If Publish reports overlapping changes, follow Publishing Changes and Resolving Conflicts. Do not use Publish ▾ › Get the latest from GitHub during an active resolution, because that action is intentionally locked while your saved work is being protected.

Connection Issues

"Disconnected" Status

Symptoms: The status dot in the header is red ("Disconnected from your workspace"). 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 workspace: it may have stopped. On the dashboard, the project row shows whether its environment is Running or Stopped, with a button to start it
4. Check your internet connection

"Connecting" Status Stuck

Symptoms: The status dot stays amber ("Connecting to your workspace…") for more than a minute.

Solutions:

1. Refresh the page
2. Check that the workspace is running on the dashboard (or, for Codespaces, on 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 the PhantomStudio dashboard and click Create Env on the project

Docker Container Won't Start or Isn't Detected

Symptoms: The dashboard shows Start Locally even though you ran the Docker command, or Open Editor stays on "Connecting..." until it says "Container not responding".

Solutions:

1. Confirm the container is up: docker ps, or check Docker Desktop › Containers
2. Hit the health endpoint: curl http://localhost:<ws-port>/health should return JSON
3. Allow local network access: in Chrome or Edge, grant permission when the browser asks to reach localhost from phantomstudio.app
4. Re-issue a setup token if you see "Token expired" or "Token already used": go to the dashboard and click Start Locally again
5. Refresh the status: the refresh icon on the project row checks the container again
6. Inspect logs: docker logs phantomwp-<your-site>

See Docker Local Development for the full setup and troubleshooting reference.

"Codespace Limit Reached"

Symptoms: Can't create new Codespaces in PhantomStudio.

Solutions:

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

The Connections panel on the dashboard shows how many codespaces you have and how many are active. GitHub's free tier includes limited Codespace hours per month.

Service Status Issues

Astro Dev Server Stopped

Symptoms: The Services panel shows the Astro Dev Server as stopped ("Preview server stopped"). Preview doesn't load.

Solutions:

1. Click the status dot in the header to open Services
2. Click Restart
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 status dot in the header
2. Restart services if they show as stopped
3. Wait for startup: servers take 10-15 seconds after the workspace 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: Edits normally save on their own a moment after you stop typing. The header keeps showing Unsaved or Saving… instead of Saved.

Solutions:

1. Check connection status: the status dot must be green
2. Press Cmd/Ctrl + S to save at once
3. Check for errors in the file that might prevent saving
4. Refresh the page if the connection dropped

File Tree Not Updating

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

Solutions:

1. Wait a moment: the file tree (Code mode) 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 the file is hidden: 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 permalinks: in WordPress, Settings › Permalinks must be anything but "Plain"
4. Check security plugins: some block the REST API
5. Verify WordPress version: the 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 and password-protected posts are hidden
3. Test the API manually: https://yoursite.com/wp-json/wp/v2/posts?status=publish

WordPress Tools Fails

Symptoms: Error when clicking Create WordPress Page in WordPress Tools (the file tree's New menu in Code mode).

Solutions:

1. Check connection status: the status dot must be green
2. Check that WordPress is connected and saved in Site ▾ › WordPress. Until then, WordPress Tools says "Connect WordPress to unlock WP Tools"
3. Pick a content type (Blog, Pages, a custom post type or Search)
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. Keep images where they are: choose Keep images on existing CDN under Image Handling in Site ▾ › WordPress › Content. See CDN Mode

AI Assistant Issues

"No API Keys" Message

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

Solutions:

1. Open AI Settings (the gear icon in the 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: the status dot must be green
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 the code editor is focused (Code mode): 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: the status dot must be green
2. Verify file type: only images are supported in src/media/
3. Check file size: very large images may time out
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 in Site ▾ › WordPress
2. Check WordPress has menus: create one in Appearance › Menus
3. Verify REST API access to your WordPress site

Section Library Issues

The Section Library (Site ▾ › Section Library) was called the Component Library before.

Components Not Inserting

Symptoms: Click Insert Component 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: you may need to click Insert for the 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 PhantomStudio 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: Connect Vercel won't accept your token.

Solutions:

1. Create a new token in Vercel (Account Settings › Tokens) and paste the whole value
2. Check the team: for a team account, enter the team ID under Using a team account? (optional)
3. Check the expiration: expired tokens are refused. See Deploying to Vercel

Deployment Stuck

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

Solutions:

1. Check the provider's dashboard for detailed build logs
2. Common build issues:
   • Missing dependencies in package.json
   • Syntax errors in code
   • Missing environment variables
3. Stop and deploy again if it seems stuck: Publish ▾ › Stop tracking this deploy, then Publish ▾ › Deploy now

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 the deployment finished: Publish ▾ shows the live site's status, and Publish ▾ › Deploy history lists recent deployments
4. Check you published your changes: deployments build what's on GitHub
5. Static pages need a deploy to show new WordPress content. See Deploy Hooks

Getting Help

If your issue isn't listed here:

Check Other Documentation

• IDE Overview
• WordPress Connection
• Docker Local Development
• 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. Send it from Help ▾ › Send Feedback in the editor, or contact support

Quick Reference