> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/help/troubleshooting.md).

# Troubleshooting

Step-by-step fixes for specific issues you might encounter while using Protoboard.

Specific problems, specific fixes. Each scenario below describes what you're seeing, why it happens, and how to resolve it.

{% hint style="info" %}
**General approach:** When something goes wrong, start simple. Refresh the page, check your internet connection, and make sure you're looking at the right board. Most issues have straightforward causes.
{% endhint %}

***

## Validation shows no results

**What you see:** You open Board Review (shield icon) and run DRC, but the results panel is empty: no errors, no warnings, nothing.

**Why it happens:** DRC only validates **harnesses**, the connections between parts. If your board has parts but no harnesses, there's nothing for the DRC to check.

**How to fix it:**

{% stepper %}
{% step %}

### Check that your parts are connected

Select any part on the canvas. If it has no harnesses attached, the DRC has nothing to validate for that part. You need at least one harness between two parts before DRC produces output.
{% endstep %}

{% step %}

### Create a harness

Hover near the edge of a part until a connection handle appears. Drag from one part to another to create a harness. Then re-run DRC.
{% endstep %}

{% step %}

### Verify interface links exist

A harness alone isn't enough; it needs at least one **interface link** inside it. Select the harness and check the Inspector panel. If the interface link section is empty, create one by pairing compatible interfaces.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Related:** [Connections & Compatibility](/user-guide/connections-and-compatibility.md) explains how harnesses, interface links, and function links work together.
{% endhint %}

***

## Part not found in the library

**What you see:** You search the Parts Bin for a specific component and it doesn't appear in the results.

**Why it happens:** The parts library is growing but doesn't include every component yet. The search may also not match your exact query phrasing.

**How to fix it:**

{% tabs %}
{% tab title="Try different search terms" %}
The Parts Bin uses AI-powered semantic search. Try:

* The **manufacturer name** plus **part number** (e.g., "Adafruit BME280")
* A **descriptive phrase** (e.g., "I2C temperature humidity sensor")
* A **shorter version** of the name (e.g., "BME280" instead of "Bosch BME280 Environmental Sensor")
* A **category** search (e.g., "motor driver" or "boost regulator")
  {% endtab %}

{% tab title="Create a blank part" %}
If the part genuinely isn't in the library, create a **blank part** and define its interfaces and resources manually. This lets you continue designing while the library catches up. See the [Breadboard from Blank Parts](/tutorials-and-examples/breadboard-from-blank-parts.md) tutorial for a walkthrough.
{% endtab %}

{% tab title="Ask ProtoBot" %}
Open ProtoBot and ask: "Find me a 3.3V I2C accelerometer." ProtoBot can search the library using different strategies and may find parts that a simple text search missed.
{% endtab %}
{% endtabs %}

***

## ProtoBot not responding

**What you see:** You send a message to ProtoBot and nothing happens: no response, no loading indicator, or a generic error message.

**Why it happens:** Several possible causes: exhausted energy balance, model availability issues, or network connectivity problems.

**How to fix it:**

{% stepper %}
{% step %}

### Check your energy balance

Open the ProtoBot panel and look at your Wh usage. If you've used up your daily allowance, ProtoBot can't process new requests until it refreshes (every 24 hours from your first message).
{% endstep %}

{% step %}

### Try a different model

If the currently selected model is experiencing issues, switch to a different one. Open the model selector in the ProtoBot panel and choose an alternative. Some models may be temporarily unavailable.
{% endstep %}

{% step %}

### Refresh the page

A simple browser refresh often resolves connection-related issues. Your conversation history is preserved.
{% endstep %}

{% step %}

### Check your internet connection

ProtoBot requires a server connection to process requests. If you're on an unstable network, the request may have failed silently.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Model note:** Some Google AI models are currently disabled due to compatibility issues. If you selected one of these models, switch to a different provider. See [Known Limitations](/help/known-limitations.md).
{% endhint %}

***

## Harness shows red but parts seem compatible

**What you see:** You created a harness between two parts that should work together, but the DRC shows INCOMPATIBLE or NOT\_CONFIGURED (red).

**Why it happens:** The harness exists, but the **interface link** inside it may be misconfigured: wrong interfaces paired, missing function links, or unallocated resources.

**How to fix it:**

{% stepper %}
{% step %}

### Check the interface link pairing

Select the harness and open the Inspector. Look at which interfaces are paired. Make sure the protocol types match (both I2C, both SPI, etc.) and the roles are complementary (master to slave, output to input).
{% endstep %}

{% step %}

### Check function links

Inside the interface link, verify that the individual signals are mapped correctly. For example, an I2C connection needs SCL-to-SCL, SDA-to-SDA, and ideally VCC-to-VCC and GND-to-GND.
{% endstep %}

{% step %}

### Check resource allocation

Even with correct interface and function links, the DRC may flag the connection if physical resources (pins) haven't been assigned. Look for the resource allocation section in the Inspector and assign specific pins.
{% endstep %}

{% step %}

### Recreate the harness

If the harness is thoroughly misconfigured, it may be faster to delete it and create a new one. Let auto-detect propose the interface link, then refine from there.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**More detail:** The [Common DRC Failures](/tutorials-and-examples/common-drc-failures.md) tutorial walks through five common failure patterns with step-by-step diagnosis.
{% endhint %}

***

## Save failed

**What you see:** You get an error when trying to save your board, or changes don't seem to persist.

**Why it happens:** Usually a network issue. Protoboard syncs to the cloud, so saving requires a stable internet connection.

**How to fix it:**

{% tabs %}
{% tab title="Check your connection" %}
Verify you have internet access. Try loading another website. If your connection is unstable, wait for it to stabilize and try saving again.
{% endtab %}

{% tab title="Try Save As" %}
If the normal save keeps failing, try exporting your board as a local file (if available). This creates a backup you can re-import later.
{% endtab %}

{% tab title="Check autosave" %}
Protoboard autosaves drafts periodically. If your session ended unexpectedly, check for autosaved drafts when you next open the board. Your most recent changes may already be preserved.
{% endtab %}
{% endtabs %}

***

## Canvas is blank after opening a board

**What you see:** You open a board that previously had parts, but the canvas is empty.

**Why it happens:** The board file may have failed to load properly, or there may be a sync issue between the local cache and the server.

**How to fix it:**

{% stepper %}
{% step %}

### Refresh the browser

A full page refresh (Ctrl+Shift+R or Cmd+Shift+R) forces the browser to reload everything from the server, bypassing the cache.
{% endstep %}

{% step %}

### Check autosave drafts

Look for any autosaved versions of the board. Protoboard may have a draft from before the issue occurred.
{% endstep %}

{% step %}

### Check board selection

Make sure you opened the correct board. If you have multiple boards with similar names, you may have opened the wrong one.
{% endstep %}

{% step %}

### Contact support

If the board is genuinely corrupted and no autosave exists, reach out through the feedback button with the board name and approximate time of last successful save. The team may be able to recover it from server-side backups.
{% endstep %}
{% endstepper %}

***

## ProtoBot gives an irrelevant or wrong suggestion

**What you see:** ProtoBot suggests a fix or action that doesn't match what you're trying to do.

**Why it happens:** AI quality depends on the model you've selected and the context you've provided. Lighter models may misunderstand complex requests.

**How to fix it:**

{% tabs %}
{% tab title="Switch to a more capable model" %}
Open the model selector in the ProtoBot panel and choose a heavier model. More capable models handle nuanced design questions better, though they consume more energy per interaction.
{% endtab %}

{% tab title="Provide more context" %}
Be specific in your prompts. Instead of "fix my board," try:

> "The I2C harness between the Arduino Uno and the BME280 shows PARTIALLY\_CONFIGURED. I think it needs pin allocation. Can you assign A4 to SDA and A5 to SCL?"

The more context you give, the better ProtoBot can help.
{% endtab %}

{% tab title="Break the task into smaller steps" %}
Instead of asking ProtoBot to do everything at once, break complex tasks into individual steps:

1. "Place an Arduino Uno Rev3 on the canvas"
2. "Place a BME280 sensor next to it"
3. "Create an I2C harness between them"
4. "Allocate I2C pins on the Arduino"

This gives ProtoBot less room to misinterpret your intent.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Related:** [prompt patterns](/protobot/how-to-use.md#prompt-patterns) has tested prompts for common ProtoBot tasks.
{% endhint %}

***

## BOM shows missing prices or supplier data

**What you see:** Some parts in the BOM panel have no pricing or supplier information.

**Why it happens:** Not all parts have supplier data linked yet, especially newer or less common components. Blank (custom) parts won't have supplier data unless you add it manually.

**How to fix it:**

{% stepper %}
{% step %}

### Click Refresh Prices

The BOM panel has a refresh button that re-fetches the latest supplier data. Pricing data is periodically updated and may have been added since you last loaded the board.
{% endstep %}

{% step %}

### Check for blank parts

Custom blank parts won't have supplier data. Select the part on the canvas, open the Inspector, and manually add the manufacturer, part number, and estimated cost. This information will then appear in the BOM.
{% endstep %}

{% step %}

### Use external sources

For parts without automatic pricing, use the datasheet URL (if available) to find the part on distributor websites. You can add this information manually to the part template.
{% endstep %}
{% endstepper %}

***

## I accidentally deleted a part or harness

**What you see:** A part or harness you needed is gone from the canvas.

**Why it happens:** Accidental deletion, usually via the Delete key or a context menu action.

**How to fix it:**

* **Undo:** Press **Ctrl+Z** (or **Cmd+Z** on Mac) to undo the deletion. Protoboard supports multiple undo levels.
* **Autosave:** If you've made many changes since the deletion, check whether an autosaved draft from before the deletion is available.
* **Re-add:** If undo doesn't work, re-add the part from the Parts Bin and recreate the harness. Your other connections won't be affected.

***

## Still stuck?

If none of these scenarios match your issue:

1. **Check** [**Known Limitations**](/help/known-limitations.md): the issue might be a known constraint
2. **Ask ProtoBot**: describe the problem in natural language and see if it can help
3. **Use the feedback button**: report the issue with screenshots and reproduction steps
4. **Check the** [**FAQ**](/help/faq.md): your question may be answered there

***

## Related pages

* [**FAQ**](/help/faq.md): General questions about Protoboard
* [**Known Limitations**](/help/known-limitations.md): Current constraints and expected behavior
* [**Common DRC Failures**](/tutorials-and-examples/common-drc-failures.md): Learn to diagnose DRC failures
* [**Fixing Errors**](/user-guide/fixing-errors.md): Step-by-step error resolution workflow


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.protoboard.xyz/help/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.