> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bymiles.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common Miles issues and what to try next.

Use this page when Miles gets stuck, cannot connect, or produces something unexpected. Most issues are easier to solve if you keep the current site open and avoid starting duplicate work.

For coding-agent-specific issues, see [Coding-agent troubleshooting](/coding-agent/troubleshooting).

## Miles is asking too many questions

Miles asks questions when it needs more context to make better design decisions. If you want it to move forward, say so clearly:

```text theme={"dark"}
Use your best judgment and continue.

Show me the brief before the full build starts.
```

You should still review the brief and design directions before the full build.

## The design directions do not fit

Tell Miles what feels wrong and ask for new directions:

```text theme={"dark"}
None of these feel right.

Make the direction more editorial, warmer, and less corporate.
```

Specific feedback works better than "try again."

## A build or conversion is taking a while

Site builds and theme conversions can take several minutes. Keep the dashboard open when a browser connection is needed.

If a coding-agent command was interrupted, ask the agent to check Miles status or wait for the current operation instead of starting a duplicate build.

## The plugin cannot connect

Check that:

* the plugin is installed and activated
* you are signed in with the right Miles account
* you have WordPress administrator permissions
* your browser allows the dashboard connection flow
* the site can reach the Miles server

Then reopen `Appearance > Miles`.

Common causes include blocked popups, third-party cookie restrictions, signing in with the wrong Miles account, security plugins or firewalls blocking outbound requests, and WordPress REST API restrictions.

If `Appearance > Miles` is missing, confirm the plugin is active under `Plugins`, then confirm you are using a WordPress administrator account. If the import list is empty, confirm the plugin is connected to the same Miles account you used for the design sandbox.

## Miles says site protection blocked a change

This usually means Miles is locked and the requested action needs approval.

Safer options:

* ask Miles to create a draft page instead
* approve the specific change if an approval card appears
* publish manually after review
* unlock Miles only in an environment you can restore

## A new section was inserted but the old one stayed

This can happen when WordPress editor state changes while Miles is generating a replacement. Review the page and remove the old section manually if needed.

## Credits are low or empty

Top up from **Settings → Subscription**, then retry the operation.

See [Credits](/account/credits) and [Plans, upgrades, and cancellation](/account/plans).

If the dashboard still shows the old balance after a top-up or plan change, refresh the dashboard, reopen the Miles plugin if you are in WordPress, and retry the operation. Avoid starting a duplicate build while the original task is still running.

## A file upload failed

Try a smaller file, a different file type, or describe the content in text. See [Uploads and moderation](/safety/uploads-and-moderation).

## An external URL could not be read

Miles may block private, local, internal, or inaccessible URLs. Attach screenshots or summarize the relevant content. See [External sites and screenshots](/safety/external-sites).

## Something important looks wrong

Stop and review the site before continuing. Preserve backups and avoid approving broad changes until you understand what will change.

## What to send support

If you still need help, include:

* your Miles account email
* the site name and WordPress URL, if relevant
* whether the site is Sandbox, local, Staging, or Development
* the action you asked Miles to perform
* the approximate date and time
* any visible error message or `error_id`
* a screenshot of the plugin, dashboard, approval card, or command output
* the WordPress version, PHP version, and Miles plugin version for plugin issues