Troubleshooting

Something isn’t working as expected? Find your case below. When in doubt, remember that nothing is ever lost: every change is a version, and you can go back to any of them.

The preview stays blank or doesn’t show

Start by looking at what the preview panel shows.

What you see	What’s happening	What to do
Highwind is building your app	The agent is writing the first version: the app shows as soon as the page exists.	Wait a few seconds.
Starting the preview…	The project’s environment is waking up (see below).	Wait; usually a few seconds.
Preparing version N…	You’re viewing an old version, which starts in a temporary environment.	Wait, or go back to the current version.
An error message and Retry	The preview couldn’t start.	Click Retry.
An empty page, with no message	The app crashed while loading, or you’re on an address that doesn’t exist.	See the steps below.

The environment is waking up

Each project runs in its own isolated environment. To avoid wasting resources, it’s put to sleep after 15 minutes without activity: when you reopen the project, the preview restarts within a few seconds, with all your files. After 24 hours without activity, the environment is recreated from the last saved version, which can take a bit longer. You don’t have to do anything: it’s automatic. If you send a request at that moment, the chat shows Preparing the environment… while the agent starts.

An empty page with no message

Click Reload (the circular arrow in the preview bar).
Check the address in the preview bar: if you’re on a page that doesn’t exist, clear the path and type / to go back to the app’s home page.
If a red The app ran into an error banner shows at the bottom of the preview (often of type Blank page), click Fix (see the next section).
If nothing changes, go back to the previous version from the version badge, then ask for the change differently.

Highwind watches the preview while you use it. When the app runs into a problem, a red The app ran into an error banner (or The app ran into N errors) shows at the bottom of the preview, with the type of error:

Exception: an error in the code while it runs;
Unhandled rejection: a background operation that failed (often a network call);
console.error: an error reported by the app itself;
Compilation: the code doesn’t compile;
Blank page: nothing shows.

Three buttons:

Details: shows the full message of each error;
Fix: sends the errors to the agent, which repairs them. It’s a request like any other: it creates a version and uses credits;
Dismiss (the cross): hides the banner.

If the error comes back after Fix, tell the agent what you were doing when it appeared (“the error happens when I click Checkout with an empty cart”), or go back to the last version that worked.

The agent stopped or failed

What you see	What happened	What to do
You clicked Stop the agent	The request is interrupted. The work already done is kept in a version.	Start again with a more specific request. A request stopped before any file changed costs nothing.
“Something went wrong: …”	A technical problem interrupted the request.	A failed request isn’t charged. Send your request again, or write “Continue”.
“I stopped this run: it reached the limit of 12 credits per request…”	The request was too big. The work done is saved.	Split what’s left into smaller requests.
A Some errors remain to be fixed step at the end	The agent ran its fixing passes without solving everything.	Ask “Fix the remaining errors”, or use Fix in the preview.
“The agent is already working on another of your projects: wait until it’s done.”	The agent works on only one project at a time per account.	Wait for the other request to finish, or stop it.
“Too many messages for now: try again in …”	You’ve reached the hourly message limit.	Try again after the stated delay. Design mode remains available.
“Highwind is paused for a moment…”	App building is paused for everyone for a while.	Try again a bit later. Your published apps stay online.
“Save or discard your code changes before sending a message.”	You have unsaved changes in the Code tab.	Save (`Ctrl` + `S`) or Discard in the Code tab.

Out of credits

When your balance runs out, the text box is blocked and a message tells you when credits come back: “You’re out of credits for today: more arrive at …” (or “You’re out of credits this month: more arrive on …” if you’ve reached the monthly cap).

Daily credits come back every night at midnight (UTC), and unused ones don’t carry over.
The monthly cap resets on the 1st of the month.
Any bonus credits, which never expire, are used once the day’s credits run out.

In the meantime, everything that doesn’t make the agent work stays available: Design mode, editing code in the Code tab, versions, and publishing and updating your apps. Your published apps stay online. See Credits.

The published site is different from the preview

Check that the latest version is published. Open the Publish menu: if it says “vN isn’t live yet.”, click Update. The preview always shows the latest version; the live site shows the latest published version.
Reload the site’s page in your browser (clearing the cache if needed) to be sure you see the new version.
If publishing failed, the menu shows “Publishing failed: …” with the reason (for example a failed build). Ask the agent to fix the error, then publish again.
If a feature that goes through the server (a form, sending an email, calling a service) works in the preview but not online, open the logs: Server logs button in the preview bar, then the Live tab. You’ll see each call to the published app’s /api routes and its errors, over the last 24 hours, a few seconds late. You can also tell the agent: “It works in the preview but not online”; it can read those same logs.

Other normal or common differences:

The Highwind badge: published apps show a small “Made with Highwind” badge.
The Live tab is empty: “This app isn’t published yet” (publish it first) or “The published app has no server (static site)” (it has no /api routes, so no live logs).
Too many requests: a published app’s /api routes are limited per visitor and per minute to prevent abuse. Beyond that, they answer with an error for a minute.
A changed key: a key changed in the project’s secrets also applies to the live app, without republishing.
Publishing blocked: if the app looks like a phishing page, or if its database has a critical security hole, publishing is refused. For security holes, the Publish menu lists the issues with Fix with the agent. See Publishing.

A connector key is missing or refused

When a feature needs an outside service, the agent shows a card in the chat: The agent needs a key or The agent needs your … connection. There you can choose Use a connection from your account (a key you already saved) or paste a new key, then Add. The key is encrypted and never shown to the agent.

The app is built anyway, but the feature in question answers with a clear error as long as the key is missing. To add it later: Project settings → Connectors (or → Secrets for a key outside the catalog). The Where to find the key link tells you where to get it from the service.

Problems connecting to Kameleoon, Notion, Linear or Figma

Context sources and Kameleoon are connected from the Connectors page in the sidebar.

Notion or Linear: you connect in a window. If it doesn’t open, allow pop-ups for highwind.app. If the agent tells you a source is unreachable, open its card, click Disconnect then Connect to reconnect it.
Figma: paste a Personal access token created in Figma (Settings → Security → Personal access tokens) with read-only “File content” and “Current user” scopes.
Kameleoon: paste your account’s Client ID and Client secret (in Kameleoon: your profile at the top right → My profile → “See my API credentials”). The agent gets the same rights as your account.

Common Kameleoon errors:

Symptom	Cause	Fix
The Kameleoon mode doesn’t show in the left panel	You need both the Kameleoon account connected and the project linked to a site (site code added by the app’s Kameleoon connector).	Connect the account on the Connectors page, then ask the agent to install Kameleoon in the app.
Read-only in the panel	Edits aren’t allowed.	Turn on Allow the agent to make changes on the Kameleoon source (Connectors page).
Rate limit reached	The Kameleoon API limits the number of calls per minute.	Wait a minute, then Refresh.
Access refused by Kameleoon	Your Kameleoon account lacks the required permission.	Check your permissions in Kameleoon.
Site not found	The project’s site code doesn’t belong to this Kameleoon account.	Check the site code in Project settings → Connectors.
“Results are still being computed”	Kameleoon computes results asynchronously.	Try again in a moment.

For a React app, also remember to turn on support for dynamic sites in your Kameleoon project. See Set up Kameleoon.

Design mode or selection doesn’t work

“The preview isn’t ready yet”: wait for the preview to load.
“Wait for the agent to finish”: Design mode is unavailable while the agent works.
“Not available on an old version”: go back to the current version.
“This element changed in the code: click it again in the preview”: the agent or you changed the file in the meantime; select the element again.
“This element’s style is computed in the code”: this setting can’t be edited directly; click Ask the agent.
On an older project, some features (selection, Design mode, dark mode preview) arrive when its environment is recreated, after 24 hours without activity.

Restore a version

Every request to the agent, every editing session and every code save creates a version. To go back:

Click the version badge (for example v7) next to the project name, at the top of the editor: the History opens. You can also click the version pill under one of the agent’s replies.
Pick the version you want. The preview shows it read-only (the badge changes color).
Check that it’s the right one, then click Restore this version.
Highwind creates a new version identical to the old one, and a message confirms it in the chat. The versions in between stay in the history: you can still go back to them.

See Versions.

Other situations

The sign-in link is invalid or has expired: request a new link from the Sign in page and open it in the same browser.
“The account … doesn’t have access yet”: Highwind is invite-only; request an invite from that screen.
“Image too large (5 MB max)”: shrink the image before uploading it. A project can hold at most 100 images.
The app’s database was deleted: as long as an app isn’t published, its database is deleted after 24 hours without activity. Enable the backend again in Project settings → Backend: the tables are recreated, not the data. See Database.