Troubleshooting

Start with the symptom that matches what you see. Most problems come from the project setup, a missing preview requirement, an unavailable assistant, or a GitHub permission.

Git is missing

Git is mandatory for Hexby. In Terminal or PowerShell, run:

git --version

If the command is not found, install Git from the official macOS, Windows, or Linux page, then restart Hexby.

GitHub CLI (gh) is optional and is not required to open a project or share a change through Hexby.

The project will not open

Check that:

1. You selected the project root, not a src folder or build-output folder.
2. You have access to the project files.
3. The project uses React or Preact with Vite or Next, or Angular with the Angular CLI.
4. Dependencies are installed on the machine running Hexby.
5. The project has any required environment values or local services available.

The project root normally contains package.json, source files, and a lockfile. If the project is remote, choose it in the project picker or open a local checkout of the repository.

The canvas is empty or incomplete

Wait for first analysis to finish. If the canvas is still incomplete:

• Reset any active search or component filters.
• Confirm that the correct project and branch are open.
• Check whether only previews are missing or whether pages and components are missing too.
• Reopen the project after installing dependencies.

If only some cards are empty, select one and read its preview status. A blocked component is different from a project-wide analysis failure.

Analysis is not progressing

Check the progress card:

• Scanning project means Hexby is reading the project and its setup.
• Finding components means pages, components, and relationships are being identified.
• Preparing to render means the preview environment is being prepared.
• Rendering previews means cards are being captured; a completed/total count may appear.

If the same status remains without moving, confirm that dependencies and Git are available and that the project does not require unavailable environment values or services. Then close and reopen the project.

A component says “Preview render failed”

The component was found, but Hexby could not render it with the information available in isolation. Common requirements include data, a provider, a route, environment values, or a meaningful state.

Open the component to read the reason. Use its fix or enrichment action when available, or use Preview App to inspect the component in the full application context. See Enrich Component Previews with AI for preview-only data.

A preview is stale or does not update

1. Wait for the refresh to finish.
2. Confirm that you changed the project currently open in Hexby.
3. Check Code View for the saved source and changed-file indicator.
4. Reopen the component or page.
5. If the issue is route- or provider-specific, check Preview App.

If the preview still shows the old result, review the changed file and use Get Help from the workspace settings. Include the project, component, and the exact status message.

Preview App will not start

Check the command shown in Preview App:

• Dependencies are installed.
• The command works from the project root.
• The command uses the project’s normal package manager.
• The port is not already in use.
• Required environment values are available locally.

If Hexby detected the wrong command, set the project’s development command in Preview App and restart it. Read the first concrete startup error before changing unrelated project files.

An AI assistant will not connect

Confirm that:

1. The assistant is installed on the same machine.
2. You are signed in to the assistant outside Hexby.
3. Hexby is running as the same user that owns the assistant configuration.
4. Any browser sign-in, device code, or API-key step was completed.
5. The assistant is not already busy or locked by another session.

Hexby does not install the assistant or supply its usage credits. Check the assistant’s own status and account if the connection continues to fail.

The assistant made an unexpected change

Review the changed files in Code View and open Review Changes. Ask the assistant to explain or revert the specific change, then inspect the next diff. Use Project Guidelines to record a rule that should apply to future requests. Do not share the change until unrelated edits are resolved.

Changes do not appear in the review

Confirm that the source file was saved and that the correct project and branch are open. Preview-only values and enrichment data do not create production source changes.

If there is still no changed-file list, the assistant may not have written the project source. Ask it to make the requested change, then wait for the preview to refresh.

GitHub sharing fails

Check that:

• The GitHub account is authorized in Hexby.
• The account can access the selected repository.
• The correct repository and branch are linked.
• There is a saved source change or unpushed commit to share.
• An organization approval is not blocking the GitHub connection.

If the repository is wrong, change it before sending. If GitHub reports a conflict or missing base, resolve it in the normal Git workflow and try again.

Get more help

Open Settings or Get Help from the workspace and include:

• The project name
• The view and component involved
• The status or error message
• What you expected to happen
• What happened instead

Do not include passwords, API keys, tokens, or production secrets in a help request.

Next step

Use Reference for requirements, status meanings, shortcuts, supported project types, and common terms.